Docs/User API/Checkouts/Create

Create a checkout

Preview
POST/user/v1/checkouts

Create a new checkout.

query parameters

  • submit

    boolean

    Attempt to submit checkout if ready and due amount is zero.

body parameters

  • organizationId

    string

    The identifier of the organization.

    This must be provided for organization checkouts.

  • type

    enum

    The type of the checkout.

    Possible values:
    CHANGESTART_TRIALCONVERT_TRIALSTART_PAIDUPGRADE_PLANDOWNGRADE_PLANCHANGE_TERMSSWITCH_TO_MONTHLYSWITCH_TO_YEARLYCHANGE_SEATSCHANGE_PAYMENT_METHODCANCELRESTART
  • planId

    string

    The identifier of the plan.

    This allows you to specify the currently selected plan.

Returns

  • id

    string

    The system-assigned identifier of the checkout.

  • type

    enum

    The type of checkout.

    Possible values:
    CHANGESTART_TRIALCONVERT_TRIALSTART_PAIDUPGRADE_PLANDOWNGRADE_PLANCHANGE_TERMSSWITCH_TO_MONTHLYSWITCH_TO_YEARLYCHANGE_SEATSCHANGE_PAYMENT_METHODCANCELRESTART
  • state

    enum

    The state of the checkout.

    Possible values:
    STEPS_REQUIREDREADYPROCESSINGSUCCEEDEDFAILEDCANCELED
  • error

    Status

    The checkout error.

  • currencyCode

    string

    The currently selected currency code.

  • plans

    Plan[]

    The plans available for checkout.

  • paymentMethod

    PaymentMethod

    The payment method for the checkout.

  • fullName

    string

    The company or individual's full name.

  • address

    Address

    The billing address.

  • steps

    CheckoutStep[]

    The steps required to complete the checkout.

  • items

    CheckoutItem[]

    The products included in the checkout.

  • discounts

    CheckoutDiscount[]

    The discounts applied to the checkout.

  • subtotalAmount

    string

    The subtotal amount for the checkout.

    This includes item-level discounts.

  • discountAmount

    string

    The top-level discount amount.

    This does not include item level discounts.

  • taxAmount

    string

    The tax amount for the checkout.

    This is for rendering purposes only and is not the reported tax amount.

  • totalAmount

    string

    The total amount for the checkout.

  • balanceAppliedAmount

    string

    The amount applied to the checkout from the balance.

    A negative amount means a debit from the account balance. A positive amount means a credit to the account balance.

  • dueAmount

    string

    The total amount minus any credits automatically associated with the invoice.

  • renewAmount

    string

    The normal total recurring amount.

    This does not include any time-limited discounts.

curl https://api.userhub.com/user/v1/checkouts \
  -H "UserHub-Api-Key: $USERHUB_USER_KEY" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  --json '{
    "organizationId": "org_28seyVGVL1got6"
  }'
Response bodyJSON
{
  "id": "co_CNUE9JoJE2dNa8FowJHSy",
  "type": "CHANGE",
  "state": "READY",
  "currencyCode": "USD",
  "plans": [
    {
      "id": "plan_2wnGzPMSrDBYK5:ukfHizos:monthly:usd",
      "state": "AVAILABLE",
      "uniqueId": "pro:ukfHizos:monthly:usd",
      "displayName": "Pro",
      "description": "The pro plan.",
      "tier": "TIER1",
      "currencyCode": "USD",
      "interval": {
        "quantity": 1,
        "unit": "MONTH"
      },
      "revision": {
        "id": "plan_2wnGzPMSrDBYK5:ukfHizos",
        "selected": true,
        "latest": true
      },
      "selected": true,
      "default": true,
      "trial": {
        "days": 7
      },
      "items": [
        {
          "type": "SEAT",
          "product": {
            "id": "pd_3fNK5BXs9C1Fdc",
            "uniqueId": "pro-seat",
            "displayName": "Pro seat"
          },
          "price": {
            "id": "pr_HFULbg4GRQEkV6",
            "currencyCode": "USD",
            "billingMode": "FIXED_TERM",
            "interval": {
              "quantity": 1,
              "unit": "MONTH"
            },
            "fixed": {
              "amount": "5"
            }
          }
        }
      ]
    },
    {
      "id": "plan_2wnGzPMSrDBYK5:ukfHizos:yearly:usd",
      "state": "AVAILABLE",
      "uniqueId": "pro:ukfHizos:yearly:usd",
      "displayName": "Pro",
      "description": "The pro plan.",
      "tier": "TIER1",
      "currencyCode": "USD",
      "interval": {
        "quantity": 1,
        "unit": "YEAR"
      },
      "revision": {
        "id": "plan_2wnGzPMSrDBYK5:ukfHizos",
        "selected": true,
        "latest": true
      },
      "trial": {
        "days": 7
      },
      "savings": {
        "percentage": 16
      },
      "items": [
        {
          "type": "SEAT",
          "product": {
            "id": "pd_3fNK5BXs9C1Fdc",
            "uniqueId": "pro-seat",
            "displayName": "Pro seat"
          },
          "price": {
            "id": "pr_36La7Y1xhx2qWv",
            "currencyCode": "USD",
            "billingMode": "FIXED_TERM",
            "interval": {
              "quantity": 1,
              "unit": "YEAR"
            },
            "fixed": {
              "amount": "50"
            }
          }
        }
      ]
    }
  ],
  "steps": [
    {
      "type": "TERMS",
      "state": "OPTIONAL"
    },
    {
      "type": "PAYMENT_METHOD",
      "state": "OPTIONAL"
    }
  ],
  "items": [
    {
      "id": "uCjaZQh9",
      "displayName": "Pro seat",
      "inputType": "HIDDEN",
      "type": "SEAT",
      "unit": "SEAT",
      "price": {
        "id": "pr_HFULbg4GRQEkV6",
        "currencyCode": "USD",
        "billingMode": "FIXED_TERM",
        "interval": {
          "quantity": 1,
          "unit": "MONTH"
        },
        "fixed": {
          "amount": "5"
        }
      },
      "quantity": 1,
      "subtotalAmount": "0",
      "discountAmount": "0",
      "renewAmount": "5"
    }
  ],
  "discounts": [],
  "subtotalAmount": "0",
  "discountAmount": "0",
  "taxAmount": "0",
  "totalAmount": "0",
  "dueAmount": "0",
  "renewAmount": "5"
}
PreviousThe checkout object
NextGet a checkout

Build software thatmonetizes
$

Subscribe to monthly product updates

© 2025 UserHub

Integrations

    UserHub & Auth0UserHub & Stripe BillingUserHub & Google CloudUserHub & FirebaseUserHub & custom auth