--- title: "Creates a new checkout session." method: POST path: "/v1/checkouts" tags: ["Checkouts"] --- # Creates a new checkout session. `POST /v1/checkouts` Create a new checkout session to accept one-time payments or start subscriptions. Returns a checkout URL to redirect customers. ## Request body - CreateCheckoutRequest - `request_id` string — Identify and track each checkout request. - `product_id` string, required — The ID of the product associated with the checkout session. - `units` number — The number of units for the order. - `custom_price` integer — Override the unit price of the product for this checkout session, in cents (e.g. 1500 = $15.00). The product currency is used, and the amount is per unit: with `units: 3` and `custom_price: 1500` the customer pays 4500. Must be between 100 (one whole unit of the currency) and 99999999. Only supported for one-time payment products. Use this for dynamic pricing models such as pay-what-you-want, donations, or amounts calculated by your application. - `discount_code` string — Prefill the checkout session with a discount code. - `affiliate_code` string — Attribute this checkout to an affiliate using the affiliate's referral code (the unique code from their referral link). Use this to manually credit a sale to a specific affiliate when you already hold their code on your backend, instead of relying on referral-link clicks/cookies. The code must belong to an active affiliate of this store; an invalid, inactive, or foreign-store code is rejected. - `customer` CustomerRequestEntity - `id` string — Unique identifier of the customer. You may specify only one of these parameters: id or email. - `email` string — Customer email address. You may only specify one of these parameters: id, email. - `name` string — Customer full name. Used to prefill the name field on the checkout page. - `custom_fields` CustomFieldRequestEntity[] — Collect additional information from your customer using custom fields. Up to 3 fields are supported. - `type` 'text' | 'checkbox', required — The type of the field. - `key` string, required — Unique key for custom field. Must be unique to this field, alphanumeric, and up to 200 characters. - `label` string, required — The label for the field, displayed to the customer, up to 50 characters. - `optional` boolean — Whether the customer is required to complete the field. Defaults to `false` - `text` TextFieldConfig - `max_length` number — Maximum character length constraint for the input. - `min_length` number — Minimum character length requirement for the input. - `checkbox` CheckboxFieldConfig - `label` string — The markdown text to display for the checkbox. - `custom_field` CustomFieldRequestEntity[] — DEPRECATED: Use `custom_fields` instead. Collect additional information from your customer using custom fields. Up to 3 fields are supported. - `type` 'text' | 'checkbox', required — The type of the field. - `key` string, required — Unique key for custom field. Must be unique to this field, alphanumeric, and up to 200 characters. - `label` string, required — The label for the field, displayed to the customer, up to 50 characters. - `optional` boolean — Whether the customer is required to complete the field. Defaults to `false` - `text` TextFieldConfig - `max_length` number — Maximum character length constraint for the input. - `min_length` number — Minimum character length requirement for the input. - `checkbox` CheckboxFieldConfig - `label` string — The markdown text to display for the checkbox. - `success_url` string — The URL to which the user will be redirected after the checkout process is completed. - `metadata` object — Metadata for the checkout in the form of key-value pairs ## Response `200` Successfully created a checkout session - CheckoutEntity - `id` string, required — Unique identifier for the object. - `mode` 'test' | 'prod' | 'sandbox', required — String representing the environment. - `object` string, required — String representing the object's type. Objects of the same type share the same value. - `status` 'pending' | 'processing' | 'completed' | 'expired', required — Status of the checkout. - `request_id` string — Identify and track each checkout request. - `product` union, required — The product associated with the checkout session. - string - ProductEntity - `id` string, required — Unique identifier for the object. - `mode` 'test' | 'prod' | 'sandbox', required — String representing the environment. - `object` string, required — String representing the object's type. Objects of the same type share the same value. - `name` string, required — The name of the product - `description` string, required — A brief description of the product - `image_url` string — URL of the product image. Only png as jpg are supported - `image_urls` string[] — Ordered list of product image URLs. The first entry is the cover image (mirrored in image_url). - `features` FeatureEntity[] — Features of the product. - `id` string, required — Unique identifier for the feature. - `type` 'custom' | 'file' | 'licenseKey' | 'customerCredits', required — The type of the feature: `custom` (private note), `file` (downloadable files), `licenseKey` (license key), or `customerCredits` (customer credit grant). - `description` string, required — A brief description of the feature. - `price` number, required — The price of the product in cents. 1000 = $10.00 - `currency` string, required — Three-letter ISO currency code, in uppercase. Must be a supported currency. - `billing_type` 'recurring' | 'onetime', required — Indicates the billing method for the customer. It can either be a `recurring` billing cycle or a `onetime` payment. - `billing_period` 'every-month' | 'every-three-months' | 'every-six-months' | 'every-year' | 'every-day' | 'once', required — Billing period - `status` 'active' | 'archived', required — Lifecycle status of the product: `active` or `archived`. - `tax_mode` 'inclusive' | 'exclusive', required — Specifies the tax calculation mode for the transaction. If set to "inclusive," the tax is included in the price. If set to "exclusive," the tax is added on top of the price. - `tax_category` 'saas' | 'digital-goods-service' | 'ebooks', required — Categorizes the type of product or service for tax purposes. This helps determine the applicable tax rules based on the nature of the item or service. - `product_url` string — The product page you can redirect your customers to for express checkout. - `default_success_url` string, nullable — The URL to which the user will be redirected after successfull payment. - `custom_fields` CustomField[], nullable — Custom fields configured for the product. Collect additional information from your customer during checkout. - `type` 'text' | 'checkbox', required — The type of the field. - `key` string, required — Unique key for custom field. Must be unique to this field, alphanumeric, and up to 200 characters. - `label` string, required — The label for the field, displayed to the customer, up to 50 characters - `optional` boolean, nullable — Whether the customer is required to complete the field. Defaults to `false`. - `text` Text - `max_length` number, nullable — Maximum character length constraint for the input. - `minimum_length` number, nullable — Minimum character length requirement for the input. - `value` string, nullable — The value of the input. - `checkbox` Checkbox - `label` string, nullable — The markdown text to display for the checkbox. - `value` boolean, nullable — The value of the checkbox (checked or not). - `created_at` string, date-time, required — Creation date of the product - `updated_at` string, date-time, required — Last updated date of the product - `units` number — The number of units for the of the product. - `custom_price` integer — The per-unit price override (in cents, product currency) this checkout was created with. Only present when the checkout was created with a custom_price. One-time payment products only. - `order` OrderEntity - `id` string, required — Unique identifier for the object. - `mode` 'test' | 'prod' | 'sandbox', required — String representing the environment. - `object` string, required — String representing the object's type. Objects of the same type share the same value. - `customer` string, nullable — The customer who placed the order. - `product` string, required — The product associated with the order. - `transaction` string, nullable — The transaction ID of the order - `discount` string, nullable — The discount ID of the order - `amount` number, required — The total amount of the order in cents. 1000 = $10.00 - `sub_total` number — The subtotal of the order in cents. 1000 = $10.00 - `tax_amount` number — The tax amount of the order in cents. 1000 = $10.00 - `discount_amount` number — The discount amount of the order in cents. 1000 = $10.00 - `amount_due` number — The amount due for the order in cents. 1000 = $10.00 - `amount_paid` number — The amount paid for the order in cents. 1000 = $10.00 - `currency` string, required — Three-letter ISO currency code, in uppercase. Must be a supported currency. - `fx_amount` number, nullable — The amount in the foreign currency, if applicable. - `fx_currency` string, nullable — Three-letter ISO code of the foreign currency, if applicable. - `fx_rate` number, nullable — The exchange rate used for converting between currencies, if applicable. - `status` 'pending' | 'paid', required — Current status of the order. - `type` 'recurring' | 'onetime', required — The type of order. This can specify whether it's a regular purchase, subscription, etc. - `affiliate` string, nullable — The affiliate associated with the order, if applicable. - `created_at` string, date-time, required — Creation date of the order - `updated_at` string, date-time, required — Last updated date of the order - `subscription` union — The subscription associated with the checkout session. - string - SubscriptionEntity - `id` string, required — Unique identifier for the object. - `mode` 'test' | 'prod' | 'sandbox', required — String representing the environment. - `object` string, required — String representing the object's type. Objects of the same type share the same value. - `product` union, required — The product associated with the subscription. - ProductEntity - `id` string, required — Unique identifier for the object. - `mode` 'test' | 'prod' | 'sandbox', required — String representing the environment. - `object` string, required — String representing the object's type. Objects of the same type share the same value. - `name` string, required — The name of the product - `description` string, required — A brief description of the product - `image_url` string — URL of the product image. Only png as jpg are supported - `image_urls` string[] — Ordered list of product image URLs. The first entry is the cover image (mirrored in image_url). - `features` FeatureEntity[] — Features of the product. - `id` string, required — Unique identifier for the feature. - `type` 'custom' | 'file' | 'licenseKey' | 'customerCredits', required — The type of the feature: `custom` (private note), `file` (downloadable files), `licenseKey` (license key), or `customerCredits` (customer credit grant). - `description` string, required — A brief description of the feature. - `price` number, required — The price of the product in cents. 1000 = $10.00 - `currency` string, required — Three-letter ISO currency code, in uppercase. Must be a supported currency. - `billing_type` 'recurring' | 'onetime', required — Indicates the billing method for the customer. It can either be a `recurring` billing cycle or a `onetime` payment. - `billing_period` 'every-month' | 'every-three-months' | 'every-six-months' | 'every-year' | 'every-day' | 'once', required — Billing period - `status` 'active' | 'archived', required — Lifecycle status of the product: `active` or `archived`. - `tax_mode` 'inclusive' | 'exclusive', required — Specifies the tax calculation mode for the transaction. If set to "inclusive," the tax is included in the price. If set to "exclusive," the tax is added on top of the price. - `tax_category` 'saas' | 'digital-goods-service' | 'ebooks', required — Categorizes the type of product or service for tax purposes. This helps determine the applicable tax rules based on the nature of the item or service. - `product_url` string — The product page you can redirect your customers to for express checkout. - `default_success_url` string, nullable — The URL to which the user will be redirected after successfull payment. - `custom_fields` CustomField[], nullable — Custom fields configured for the product. Collect additional information from your customer during checkout. - `type` 'text' | 'checkbox', required — The type of the field. - `key` string, required — Unique key for custom field. Must be unique to this field, alphanumeric, and up to 200 characters. - `label` string, required — The label for the field, displayed to the customer, up to 50 characters - `optional` boolean, nullable — Whether the customer is required to complete the field. Defaults to `false`. - `text` Text - … - `checkbox` Checkbox - … - `created_at` string, date-time, required — Creation date of the product - `updated_at` string, date-time, required — Last updated date of the product - string - `customer` union, required — The customer who owns the subscription. - CustomerEntity - `id` string, required — Unique identifier for the object. - `mode` 'test' | 'prod' | 'sandbox', required — String representing the environment. - `object` string, required — String representing the object’s type. Objects of the same type share the same value. - `email` string, required — Customer email address. - `name` string, nullable — Customer name. - `metadata` object, nullable — Additional metadata associated with the customer. - `country` string, nullable, required — The ISO 3166-1 alpha-2 country code for the customer. - `created_at` string, date-time, required — Creation date of the customer - `updated_at` string, date-time, required — Last updated date of the customer - string - `items` SubscriptionItemEntity[] — Subscription items. - `id` string, required — Unique identifier for the object. - `mode` 'test' | 'prod' | 'sandbox', required — String representing the environment. - `object` string, required — String representing the object’s type. Objects of the same type share the same value. - `product_id` string — The ID of the product associated with the subscription item. - `price_id` string — The ID of the price associated with the subscription item. - `units` number, nullable — The number of units for the subscription item. - `collection_method` 'charge_automatically', required — The method used for collecting payments for the subscription. - `status` 'active' | 'canceled' | 'unpaid' | 'paused' | 'trialing' | 'scheduled_cancel' | 'past_due', required — The current status of the subscription. - `last_transaction_id` string — The ID of the last paid transaction. - `last_transaction` TransactionEntity - `id` string, required — Unique identifier for the object. - `mode` 'test' | 'prod' | 'sandbox', required — String representing the environment. - `object` string, required — String representing the object's type. Objects of the same type share the same value. - `amount` number, required — The transaction amount in cents. 1000 = $10.00 - `amount_paid` number, nullable — The amount the customer paid in cents. 1000 = $10.00 - `discount_amount` number, nullable — The discount amount in cents. 1000 = $10.00 - `currency` string, required — Three-letter ISO currency code, in uppercase. Must be a supported currency. - `type` 'payment' | 'invoice', required — The type of transaction. payment(one time payments) and invoice(subscription) - `tax_country` string, nullable — The ISO alpha-2 country code where tax is collected. - `tax_amount` number, nullable — The sale tax amount in cents. 1000 = $10.00 - `status` 'pending' | 'paid' | 'refunded' | 'partialRefund' | 'chargedBack' | 'uncollectible' | 'declined' | 'canceled' | 'void', required — Status of the transaction. - `refunded_amount` number, nullable — The amount that has been refunded in cents. 1000 = $10.00 - `order` string, nullable — The order associated with the transaction. - `subscription` string, nullable — The subscription associated with the transaction. - `customer` string, nullable — The customer associated with the transaction. - `description` string — The description of the transaction. - `period_start` number — Start period for the invoice as timestamp - `period_end` number — End period for the invoice as timestamp - `created_at` number, required — Creation date of the order as timestamp - `last_transaction_date` string, date-time — The date of the last paid transaction. - `next_transaction_date` string, date-time — The date when the next subscription transaction will be charged. - `current_period_start_date` string, date-time — The start date of the current subscription period. - `current_period_end_date` string, date-time — The end date of the current subscription period. - `canceled_at` string, date-time, nullable — The date and time when the subscription was canceled, if applicable. - `created_at` string, date-time, required — The date and time when the subscription was created. - `updated_at` string, date-time, required — The date and time when the subscription was last updated. - `discount` object — The discount applied to the subscription, if any. - `id` string — The unique identifier of the discount (e.g. dis_...). - `discountCode` string — The discount code applied to the subscription. - `name` string - `type` 'percentage' | 'fixed' - `amount` number - `duration` 'forever' | 'once' | 'repeating' - `durationInMonths` number - `metadata` object — Metadata for the subscription in the form of key-value pairs. - `customer` union — The customer associated with the checkout session. - string - CustomerEntity - `id` string, required — Unique identifier for the object. - `mode` 'test' | 'prod' | 'sandbox', required — String representing the environment. - `object` string, required — String representing the object’s type. Objects of the same type share the same value. - `email` string, required — Customer email address. - `name` string, nullable — Customer name. - `metadata` object, nullable — Additional metadata associated with the customer. - `country` string, nullable, required — The ISO 3166-1 alpha-2 country code for the customer. - `created_at` string, date-time, required — Creation date of the customer - `updated_at` string, date-time, required — Last updated date of the customer - `custom_fields` CustomField[] — Additional information collected from your customer during the checkout process. - `type` 'text' | 'checkbox', required — The type of the field. - `key` string, required — Unique key for custom field. Must be unique to this field, alphanumeric, and up to 200 characters. - `label` string, required — The label for the field, displayed to the customer, up to 50 characters - `optional` boolean, nullable — Whether the customer is required to complete the field. Defaults to `false`. - `text` Text - `max_length` number, nullable — Maximum character length constraint for the input. - `minimum_length` number, nullable — Minimum character length requirement for the input. - `value` string, nullable — The value of the input. - `checkbox` Checkbox - `label` string, nullable — The markdown text to display for the checkbox. - `value` boolean, nullable — The value of the checkbox (checked or not). - `checkout_url` string — The URL to which the customer will be redirected to complete the payment. - `success_url` string, nullable — The URL to which the user will be redirected after the checkout process is completed. - `license_keys` LicenseEntity[] — License keys issued for the order. - `id` string, required — Unique identifier for the object. - `mode` 'test' | 'prod' | 'sandbox', required — String representing the environment. - `object` string, required — A string representing the object's type. Objects of the same type share the same value. - `product_id` string, required — The ID of the product this license belongs to. - `status` 'inactive' | 'active' | 'expired' | 'disabled', required — The current status of the license key. - `key` string, required — The license key. - `activation` number, required — The number of instances that this license key was activated. - `activation_limit` number, nullable — The activation limit. Null if activations are unlimited. - `expires_at` string, date-time, nullable — The date the license key expires. Null if it does not have an expiration date. - `created_at` string, date-time, required — The creation date of the license key. - `instance` LicenseInstanceEntity - `id` string, required — Unique identifier for the object. - `mode` 'test' | 'prod' | 'sandbox', required — String representing the environment. - `object` string, required — A string representing the object’s type. Objects of the same type share the same value. - `name` string, required — The name of the license instance. - `status` 'active' | 'deactivated', required — The status of the license instance. - `created_at` string, date-time, required — The creation date of the license instance. - `feature` ProductFeatureEntity[] — DEPRECATED: Use `license_keys` instead. Features issued for the order. - `id` string, nullable — Unique identifier for the feature. - `description` string, nullable — A brief description of the feature. - `type` 'custom' | 'file' | 'licenseKey' | 'customerCredits' — The type of the feature: `custom` (private note), `file` (downloadable files), `licenseKey` (license key), or `customerCredits` (customer credit grant). - `private_note` string, nullable — Private note from the seller. This is only visible to the customer after purchase. - `file` FileFeatureEntity - `files` FeatureFileEntity[], required — List of downloadable files. - `id` string, required — Unique identifier for the file. - `file_name` string, required — The name of the file. - `url` string, required — The URL to download the file. - `type` string, required — The MIME type of the file. - `size` number, required — The size of the file in bytes. - `license_key` LicenseEntity - `id` string, required — Unique identifier for the object. - `mode` 'test' | 'prod' | 'sandbox', required — String representing the environment. - `object` string, required — A string representing the object's type. Objects of the same type share the same value. - `product_id` string, required — The ID of the product this license belongs to. - `status` 'inactive' | 'active' | 'expired' | 'disabled', required — The current status of the license key. - `key` string, required — The license key. - `activation` number, required — The number of instances that this license key was activated. - `activation_limit` number, nullable — The activation limit. Null if activations are unlimited. - `expires_at` string, date-time, nullable — The date the license key expires. Null if it does not have an expiration date. - `created_at` string, date-time, required — The creation date of the license key. - `instance` LicenseInstanceEntity - `id` string, required — Unique identifier for the object. - `mode` 'test' | 'prod' | 'sandbox', required — String representing the environment. - `object` string, required — A string representing the object’s type. Objects of the same type share the same value. - `name` string, required — The name of the license instance. - `status` 'active' | 'deactivated', required — The status of the license instance. - `created_at` string, date-time, required — The creation date of the license instance. - `customer_credits` CustomerCreditsFeatureEntity - `amount` string, required — The number of credits to grant. String to preserve BigInt precision. - `unit_label` string, nullable — Optional label for the credit unit (e.g. "tokens", "credits"). - `license` LicenseEntity - `id` string, required — Unique identifier for the object. - `mode` 'test' | 'prod' | 'sandbox', required — String representing the environment. - `object` string, required — A string representing the object's type. Objects of the same type share the same value. - `product_id` string, required — The ID of the product this license belongs to. - `status` 'inactive' | 'active' | 'expired' | 'disabled', required — The current status of the license key. - `key` string, required — The license key. - `activation` number, required — The number of instances that this license key was activated. - `activation_limit` number, nullable — The activation limit. Null if activations are unlimited. - `expires_at` string, date-time, nullable — The date the license key expires. Null if it does not have an expiration date. - `created_at` string, date-time, required — The creation date of the license key. - `instance` LicenseInstanceEntity - `id` string, required — Unique identifier for the object. - `mode` 'test' | 'prod' | 'sandbox', required — String representing the environment. - `object` string, required — A string representing the object’s type. Objects of the same type share the same value. - `name` string, required — The name of the license instance. - `status` 'active' | 'deactivated', required — The status of the license instance. - `created_at` string, date-time, required — The creation date of the license instance. - `metadata` object — Metadata for the checkout in the form of key-value pairs - `discount` object — The discount applied to the checkout, if any. - `id` string — The unique identifier of the discount (e.g. dis_...). - `discountCode` string — The discount code applied to the checkout. - `name` string - `type` 'percentage' | 'fixed' - `amount` number - `duration` 'forever' | 'once' | 'repeating' - `durationInMonths` number ## Other responses - `400` — Bad Request - Invalid input parameters - `401` — Unauthorized - Invalid or missing API key - `404` — Not Found - Resource does not exist --- [API](https://skmtc.net/creem/apis/creem-api.md) · [All operations](https://skmtc.net/creem/apis/creem-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/creem/creem-api/revisions/11305a63d3c9/schema)