CRcreem
Checkouts

Creates a new checkout session.

Changed on

Create a new checkout session to accept one-time payments or start subscriptions. Returns a checkout URL to redirect customers.

post/v1/checkouts

Request

Request body

request_idstring

Identify and track each checkout request.

product_idstring required

The ID of the product associated with the checkout session.

unitsnumber

The number of units for the order.

custom_priceinteger

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_codestring

Prefill the checkout session with a discount code.

affiliate_codestring

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.

success_urlstring

The URL to which the user will be redirected after the checkout process is completed.

metadataobject

Metadata for the checkout in the form of key-value pairs

Example request

{
  "product_id": "prod_1234567890",
  "units": 1,
  "custom_price": 1500,
  "discount_code": "SUMMER2024",
  "affiliate_code": "aff_abc123",
  "customer": {
    "id": "cust_1234567890",
    "email": "user@example.com",
    "name": "John Doe"
  },
  "custom_fields": [
    {
      "key": "companyName",
      "label": "Company Name",
      "text": {
        "max_length": 200,
        "min_length": 1
      },
      "checkbox": {
        "label": "I agree to the [terms and conditions](https://example.com/terms)"
      }
    }
  ],
  "custom_field": [
    {
      "key": "companyName",
      "label": "Company Name",
      "text": {
        "max_length": 200,
        "min_length": 1
      },
      "checkbox": {
        "label": "I agree to the [terms and conditions](https://example.com/terms)"
      }
    }
  ],
  "metadata": {
    "userId": "user_123",
    "visitCount": 42,
    "lastVisit": "2023-04-01"
  }
}

Response

Successfully created a checkout session

idstring required

Unique identifier for the object.

mode'test' | 'prod' | 'sandbox' required

String representing the environment.

objectstring 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_idstring

Identify and track each checkout request.

unitsnumber

The number of units for the of the product.

custom_priceinteger

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.

checkout_urlstring

The URL to which the customer will be redirected to complete the payment.

success_urlstring nullable

The URL to which the user will be redirected after the checkout process is completed.

metadataobject

Metadata for the checkout in the form of key-value pairs

Example response

{
  "status": "completed",
  "product": {
    "description": "This is a sample product description.",
    "image_url": "https://example.com/image.jpg",
    "image_urls": [
      "https://example.com/image.jpg"
    ],
    "features": [
      {
        "id": "feat_abc123",
        "description": "Access to premium course materials.",
        "customer_credits": {
          "amount": "100",
          "unit_label": "tokens",
          "bucket_name": "images"
        }
      }
    ],
    "usage_prices": [
      {
        "id": "price_abc123",
        "meter_id": "mtr_abc123",
        "unit_price": 0.002,
        "free_allowance": 1000,
        "cap": 50000,
        "target_account_name": "images"
      }
    ],
    "price": 400,
    "currency": "USD",
    "recurring_interval": "month",
    "recurring_interval_count": 3,
    "trial_period_days": 7,
    "trial_price": 100,
    "product_url": "https://creem.io/product/prod_123123123123",
    "default_success_url": "https://example.com/?status=successful",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  },
  "custom_price": 1500,
  "order": {
    "transaction": "tx_1234567890",
    "discount": "dis_1234567890",
    "amount": 2000,
    "sub_total": 1800,
    "tax_amount": 200,
    "discount_amount": 100,
    "amount_due": 1900,
    "amount_paid": 1900,
    "currency": "USD",
    "fx_amount": 15,
    "fx_currency": "EUR",
    "fx_rate": 1.2,
    "created_at": "2023-09-13T00:00:00Z",
    "updated_at": "2023-09-13T00:00:00Z"
  },
  "subscription": {
    "object": "subscription",
    "product": {
      "description": "This is a sample product description.",
      "image_url": "https://example.com/image.jpg",
      "image_urls": [
        "https://example.com/image.jpg"
      ],
      "features": [
        {
          "id": "feat_abc123",
          "description": "Access to premium course materials.",
          "customer_credits": {
            "amount": "100",
            "unit_label": "tokens",
            "bucket_name": "images"
          }
        }
      ],
      "usage_prices": [
        {
          "id": "price_abc123",
          "meter_id": "mtr_abc123",
          "unit_price": 0.002,
          "free_allowance": 1000,
          "cap": 50000,
          "target_account_name": "images"
        }
      ],
      "price": 400,
      "currency": "USD",
      "recurring_interval": "month",
      "recurring_interval_count": 3,
      "trial_period_days": 7,
      "trial_price": 100,
      "product_url": "https://creem.io/product/prod_123123123123",
      "default_success_url": "https://example.com/?status=successful",
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    "customer": {
      "email": "user@example.com",
      "name": "John Doe",
      "metadata": {
        "key": "value"
      },
      "country": "US",
      "external_id": "user-42",
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    "last_transaction_id": "tran_3e6Z6TzvHKdsjEgXnGDEp0",
    "last_transaction": {
      "object": "transaction",
      "amount": 2000,
      "amount_paid": 2000,
      "discount_amount": 2000,
      "currency": "USD",
      "tax_country": "US",
      "tax_amount": 2000,
      "refunded_amount": 2000
    },
    "last_transaction_date": "2024-09-12T12:34:56Z",
    "next_transaction_date": "2024-09-12T12:34:56Z",
    "current_period_start_date": "2024-09-12T12:34:56Z",
    "current_period_end_date": "2024-09-12T12:34:56Z",
    "canceled_at": "2024-09-12T12:34:56Z",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-09-12T12:34:56Z",
    "discount": {
      "id": "dis_3e6Z6TzvHKdsjEgXnGDEp0",
      "discountCode": "HOLIDAY2024"
    },
    "metadata": {
      "userId": "user_123",
      "plan": "pro"
    }
  },
  "customer": {
    "email": "user@example.com",
    "name": "John Doe",
    "metadata": {
      "key": "value"
    },
    "country": "US",
    "external_id": "user-42",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  },
  "success_url": "https://example.com/return",
  "license_keys": [
    {
      "product_id": "prod_abc123",
      "key": "ABC123-XYZ456-XYZ456-XYZ456",
      "activation": 5,
      "activation_limit": 1,
      "expires_at": "2023-09-13T00:00:00Z",
      "created_at": "2023-09-13T00:00:00Z",
      "instance": {
        "object": "license-instance",
        "name": "My Customer License Instance",
        "status": "active",
        "created_at": "2023-09-13T00:00:00Z"
      }
    }
  ],
  "feature": {
    "id": "feat_abc123",
    "description": "Get access to the full course materials.",
    "private_note": "Thank you for your purchase! Here is your access code: XYZ123",
    "file": {
      "files": [
        {
          "id": "file_abc123",
          "file_name": "ebook.pdf",
          "url": "https://storage.creem.io/files/ebook.pdf",
          "type": "application/pdf",
          "size": 1024000
        }
      ]
    },
    "license_key": {
      "product_id": "prod_abc123",
      "key": "ABC123-XYZ456-XYZ456-XYZ456",
      "activation": 5,
      "activation_limit": 1,
      "expires_at": "2023-09-13T00:00:00Z",
      "created_at": "2023-09-13T00:00:00Z",
      "instance": {
        "object": "license-instance",
        "name": "My Customer License Instance",
        "status": "active",
        "created_at": "2023-09-13T00:00:00Z"
      }
    },
    "customer_credits": {
      "amount": "100",
      "unit_label": "tokens",
      "bucket_name": "images"
    },
    "license": {
      "product_id": "prod_abc123",
      "key": "ABC123-XYZ456-XYZ456-XYZ456",
      "activation": 5,
      "activation_limit": 1,
      "expires_at": "2023-09-13T00:00:00Z",
      "created_at": "2023-09-13T00:00:00Z",
      "instance": {
        "object": "license-instance",
        "name": "My Customer License Instance",
        "status": "active",
        "created_at": "2023-09-13T00:00:00Z"
      }
    }
  },
  "metadata": {
    "userId": "user_123",
    "visitCount": 42,
    "lastVisit": "2023-04-01"
  },
  "discount": {
    "id": "dis_3e6Z6TzvHKdsjEgXnGDEp0",
    "discountCode": "HOLIDAY2024"
  }
}

Changes

  • e194a0be46dcRevision changes
    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ////////// to the response with the status

    • info

      added the optional property //////////// to the response with the status

    • info

      added the optional property ////////// to the response with the status

    • info

      added the optional property ////////// to the response with the status

    • info

      added the optional property ////////// to the response with the status

  • ab9722a7eb0cRevision changes
    • breaking

      the ///// response's property type changed from object to string for status

    • breaking

      the response's property type changed from array to no type for status

    • breaking

      the ////////// response's property type changed from object to string for status

    • info

      added to the response property allOf list for the response status