01.software Docs

Create a Checkout

Use the SDK for application integration. This read-only reference covers Commerce, Customer Auth, Membership and Events.

All HTTP operations
POST
/api/orders/checkout

A shippingAddress is required when any frozen Cart line requiresShipping !== false and the Cart has no valid stored shipping address. Request address takes precedence. recipientName, phone, postalCode, address, and detailAddress must be nonblank after trimming; otherwise Checkout creation returns HTTP 400 shipping_address_required before Cart preparation or reservations. One canonical transport with credential-specific request and response variants. Server bodies require the admitted server credential; browser/customer bodies retain their capability boundary.

Authorization

headerX-Publishable-Key<token>

Tenant publishable key for authentication (sent via X-Publishable-Key header)

Header Parameters

X-Idempotency-Key*string

Caller-generated retry identity. Reuse the same key only when retrying the same logical operation.

Match^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|ik_[A-Za-z0-9_-]{22})$
Lengthlength <= 255
Accept?"application/vnd.01software.credit-funding.v1+json"

Exact whole-value opt-in after trimming whitespace, case-insensitive. Lists, wildcards and parameters (including q/charset) retain legacy JSON. Success only: vendor Content-Type and private, no-store. Accept never grants money or authorization. Missing funding means unknown support, not zero credit. Purchase total semantics are unchanged.

Value in"application/vnd.01software.credit-funding.v1+json"

Request Body

application/json
  1. body
cartToken*string
Length1 <= length <= 512
creditAmount?integer

Exact KRW credit request. Requires verified Customer proof, enabled credit settings and ecommerce. Never clamped or retried without credit; older strict servers reject before business writes.

Range1 <= value <= 9007199254740991
customer*
shippingAddress?

Response Body

Create a Checkout result

  1. response
checkout*|||
checkoutToken*string
Length1 <= length <= 512

Examples may be generated from schemas; they are illustrative, not recorded successful API calls. Example snippets may omit required authentication headers.

Example Request
curl -X POST 'https://api.01.software/api/orders/checkout' \  -H 'X-Idempotency-Key: string' \  -H 'Content-Type: application/json' \  -d '{  "cartToken": "string",  "customer": {    "email": "user@example.com"  }}'
Example Response
{  "checkout": {    "id": "string",    "amounts": {      "currency": "string",      "subtotalMinor": 0,      "shippingMinor": 0,      "discountMinor": 0,      "totalMinor": 0    },    "customerSnapshot": {      "email": "user@example.com",      "name": "string",      "phone": "string"    },    "expiresAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "items": [      {        "id": "string",        "product": {          "id": "string",          "title": "string",          "handle": "string",          "image": "string"        },        "variant": {          "id": "string",          "title": "string",          "handle": "string",          "image": "string"        },        "productTitle": "string",        "variantTitle": "string",        "sku": "string",        "admissions": [          {            "eventId": "string",            "occurrenceId": "string",            "admissionTypeId": "string"          }        ],        "quantity": 1,        "unitPriceMinor": 0,        "discountMinor": 0,        "lineTotalMinor": 0,        "requiresShipping": true      }    ],    "shippingAddress": {      "recipientName": "string",      "phone": "string",      "countryCode": "st",      "regionCode": "string",      "postalCode": "string",      "address": "string",      "detailAddress": "string",      "deliveryMessage": "string"    },    "attributes": [      {        "key": "string",        "value": "string"      }    ],    "status": "open",    "paymentState": {      "activePaymentSession": {        "id": "string",        "provider": "toss",        "providerStatus": "requires_payment_method"      }    },    "order": null  },  "checkoutToken": "string"}

Credential variants

Credential-specific requirements from the public OpenAPI projection: Full response schemas appear in Response Body.

[
  {
    "security": [
      {
        "publishableKey": []
      },
      {
        "publishableKey": [],
        "customerBearerAuth": []
      }
    ],
    "requestSchema": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "cartToken",
        "customer"
      ],
      "properties": {
        "cartToken": {
          "type": "string",
          "minLength": 1,
          "maxLength": 512
        },
        "creditAmount": {
          "type": "integer",
          "minimum": 1,
          "maximum": 9007199254740991,
          "description": "Exact KRW credit request. Requires verified Customer proof, enabled credit settings and ecommerce. Never clamped or retried without credit; older strict servers reject before business writes."
        },
        "customer": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "email"
          ],
          "properties": {
            "email": {
              "type": "string",
              "format": "email",
              "maxLength": 254
            },
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "phone": {
              "type": "string",
              "minLength": 1,
              "maxLength": 32
            }
          }
        },
        "shippingAddress": {
          "type": "object",
          "properties": {
            "recipientName": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "phone": {
              "type": "string",
              "minLength": 1,
              "maxLength": 32
            },
            "countryCode": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            },
            "regionCode": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "postalCode": {
              "type": "string",
              "minLength": 1,
              "maxLength": 32
            },
            "address": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            },
            "detailAddress": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            },
            "deliveryMessage": {
              "type": "string",
              "maxLength": 500
            }
          },
          "required": [
            "recipientName",
            "phone",
            "postalCode",
            "address",
            "detailAddress"
          ],
          "additionalProperties": false
        }
      }
    },
    "responseSchema": "CreateCheckoutResult"
  },
  {
    "security": [
      {
        "publishableKey": [],
        "serverSecretKey": []
      }
    ],
    "requestSchema": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "cartToken",
        "customer"
      ],
      "properties": {
        "cartToken": {
          "type": "string",
          "minLength": 1,
          "maxLength": 512
        },
        "creditAmount": {
          "type": "integer",
          "minimum": 1,
          "maximum": 9007199254740991,
          "description": "Exact KRW credit request. Requires verified Customer proof, enabled credit settings and ecommerce. Never clamped or retried without credit; older strict servers reject before business writes."
        },
        "customer": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "email"
          ],
          "properties": {
            "email": {
              "type": "string",
              "format": "email",
              "maxLength": 254
            },
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "phone": {
              "type": "string",
              "minLength": 1,
              "maxLength": 32
            }
          }
        },
        "shippingAddress": {
          "type": "object",
          "properties": {
            "recipientName": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "phone": {
              "type": "string",
              "minLength": 1,
              "maxLength": 32
            },
            "countryCode": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            },
            "regionCode": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "postalCode": {
              "type": "string",
              "minLength": 1,
              "maxLength": 32
            },
            "address": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            },
            "detailAddress": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            },
            "deliveryMessage": {
              "type": "string",
              "maxLength": 500
            }
          },
          "required": [
            "recipientName",
            "phone",
            "postalCode",
            "address",
            "detailAddress"
          ],
          "additionalProperties": false
        },
        "customerToken": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "clientReferenceId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        },
        "integrationMetadata": {
          "type": "object",
          "maxProperties": 50,
          "description": "Integration metadata keys must be 1-40 characters and must not contain [ or ]. OpenAPI 3.0 cannot constrain arbitrary property names, so servers enforce key names.",
          "additionalProperties": {
            "type": "string",
            "maxLength": 500
          }
        }
      }
    },
    "responseSchema": "CreateServerCheckoutResult"
  }
]