01.software Docs

Add an item to a Cart

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

All HTTP operations
POST
/api/carts/add-item

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

Request Body

application/json
  1. body
cartToken*string
Length1 <= length <= 512
expectedRevision*integer
Range0 <= value <= 9007199254740991
productId*string
Length1 <= length <= 255
variantId*string
Length1 <= length <= 255
quantity*integer
Range1 <= value <= 99
admissions?array<>

Admissions must be unique and in canonical order by eventId, occurrenceId, then admissionTypeId. The server enforces ordering because OpenAPI 3.0 cannot express it.

Items1 <= items <= 32

Response Body

Add an item to a Cart result

application/json
  1. response
cart*
warnings*array<>

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/carts/add-item' \  -H 'X-Idempotency-Key: string' \  -H 'Content-Type: application/json' \  -d '{  "cartToken": "string",  "expectedRevision": 0,  "productId": "string",  "variantId": "string",  "quantity": 1}'
Example Response
{  "cart": {    "id": "string",    "status": "active",    "revision": 0,    "currency": "string",    "market": {      "id": "string",      "handle": "string",      "name": "string"    },    "subtotalMinor": 0,    "discountMinor": 0,    "estimatedTotalMinor": 0,    "discountCodes": [      {        "code": "string",        "applicable": true      }    ],    "attributes": [      {        "key": "string",        "value": "string"      }    ],    "items": [      {        "id": "string",        "product": {          "id": "string",          "title": "string",          "handle": "string",          "image": "string"        },        "variant": {          "id": "string",          "title": "string",          "handle": "string",          "image": "string"        },        "admissions": [          {            "eventId": "string",            "occurrenceId": "string",            "admissionTypeId": "string"          }        ],        "quantity": 1,        "unitPriceMinor": 0,        "discountMinor": 0,        "estimatedLineTotalMinor": 0,        "requiresShipping": true      }    ],    "expiresAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  },  "warnings": [    {      "code": "DISCOUNT_CODE_NOT_HONOURED",      "message": "string",      "target": "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",
        "expectedRevision",
        "productId",
        "variantId",
        "quantity"
      ],
      "properties": {
        "cartToken": {
          "type": "string",
          "minLength": 1,
          "maxLength": 512
        },
        "expectedRevision": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "productId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        },
        "variantId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        },
        "quantity": {
          "type": "integer",
          "minimum": 1,
          "maximum": 99
        },
        "admissions": {
          "description": "Admissions must be unique and in canonical order by eventId, occurrenceId, then admissionTypeId. The server enforces ordering because OpenAPI 3.0 cannot express it.",
          "type": "array",
          "minItems": 1,
          "maxItems": 32,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "eventId",
              "occurrenceId",
              "admissionTypeId"
            ],
            "properties": {
              "eventId": {
                "type": "string",
                "minLength": 1
              },
              "occurrenceId": {
                "type": "string",
                "minLength": 1
              },
              "admissionTypeId": {
                "type": "string",
                "minLength": 1
              }
            }
          }
        }
      }
    },
    "responseSchema": "CartMutationResult"
  },
  {
    "security": [
      {
        "publishableKey": [],
        "serverSecretKey": []
      }
    ],
    "requestSchema": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "cartToken",
        "expectedRevision",
        "productId",
        "variantId",
        "quantity"
      ],
      "properties": {
        "cartToken": {
          "type": "string",
          "minLength": 1,
          "maxLength": 512
        },
        "expectedRevision": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "productId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        },
        "variantId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        },
        "quantity": {
          "type": "integer",
          "minimum": 1,
          "maximum": 99
        },
        "admissions": {
          "description": "Admissions must be unique and in canonical order by eventId, occurrenceId, then admissionTypeId. The server enforces ordering because OpenAPI 3.0 cannot express it.",
          "type": "array",
          "minItems": 1,
          "maxItems": 32,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "eventId",
              "occurrenceId",
              "admissionTypeId"
            ],
            "properties": {
              "eventId": {
                "type": "string",
                "minLength": 1
              },
              "occurrenceId": {
                "type": "string",
                "minLength": 1
              },
              "admissionTypeId": {
                "type": "string",
                "minLength": 1
              }
            }
          }
        },
        "customerToken": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        }
      }
    },
    "responseSchema": "CartMutationResult"
  }
]