Skip to content

Checkout sessions

2 operations. Authenticate with your secret API key (see Authentication); failures use the shape described in Errors. Example requests read $GIEP_API_URL, your deployment’s API host.

Create a hosted checkout session

POST/v1/checkout-sessions

Redirect the shopper to url. A retry with the same Idempotency-Key returns the original session.

Authentication
API key (Bearer)
Permission
sell:manage
Idempotency-Key
Required
Success
201

Headers

  • Idempotency-Keystringrequired

    Unique per logical operation: 8-255 characters of A-Z a-z 0-9 _ - : . Retrying with the same key returns the original result and never repeats the side effect; derive it from your own order/payment id.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • checkoutIdstring · uuidrequired
  • lineItemsarray<object>required
    min 1 items · max 50 items
    Each item has 5 fields
    • productIdstring · uuid
    • titlestringrequired
      min 1 chars · max 300 chars
    • quantityintegerrequired
      min 1 · max 1000
    • unitAmountintegerrequired
      min 1 · max 100000000
    • pricesany
  • currencystringrequired
    3 chars
  • customerobject
    Fields: 4 fields
    • emailstring · email
    • namestring
      max 200 chars
    • phonestring
      max 40 chars
    • countrystring
      2 chars
  • returnUrlstring · uri
  • successUrlstring · uri
  • failureUrlstring · uri
  • cancelUrlstring · uri
  • externalOrderRefstring
    max 200 chars
  • taxLinesarray<object>
    max 20 items
    Each item has 4 fields
    • namestringrequired
      min 1 chars · max 100 chars
    • amountintegerrequired
      min 0 · max 100000000
    • inclusiveboolean
    • currencystring
      3 chars
  • totalinteger
    greater than 0
  • expiresInMinutesinteger
    Default 60min 1 · max 10080

Responses

  • 201Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 422Validation failed (invalid_request) Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.
201 response fieldsCheckoutSessionCreated
  • idstring · uuidrequired
  • tokenstringrequired

    Opaque; shown once. Used in the hosted checkout URL.

  • urlstring · urirequired
Request · cURL
curl -X POST "$GIEP_API_URL/v1/checkout-sessions" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-session-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "checkoutId": "679010dc-dba5-41d2-a1d7-5b76-d95",
  "lineItems": [
    {
      "title": "string",
      "quantity": 1,
      "unitAmount": 4999
    }
  ],
  "currency": "USD"
}'
{
  "id": "37386ae0-251d-4f38-a753-611e841d7",
  "token": "string",
  "url": "https://shop.example/url"
}

Retrieve a checkout session

GET/v1/checkout-sessions/{id}

A session as the merchant sees it: status, totals with discount, tax and shipping lines (integer minor units), payment and order ids, your externalOrderRef, accepted bumps and post-purchase offer results. Use it to confirm an outcome; never trust the return redirect alone.

Authentication
API key (Bearer)
Permission
sell:read
Idempotency-Key
Not used
Success
200

Path parameters

  • idstringrequired

Responses

  • 200Success
  • 401Missing or invalid credentials Body is an error object with code and message.
  • 403Role not permitted Body is an error object with code and message.
  • 429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.
200 response fieldsCheckoutSession
  • idstring · uuidrequired
  • checkoutIdstring · uuidrequired
  • statusstringrequired
  • currencystringrequired
    3 chars
  • subtotalintegerrequired
  • totalintegerrequired
  • paymentIdstring · uuidrequirednullable
  • orderIdstring · uuidrequirednullable
  • externalOrderRefstringrequirednullable
  • acceptedBumpIdsarray<string> · uuidrequired
  • discountCodestringrequirednullable
  • discountsarray<object>required
    Each item has 5 fields
    • discountIdstring · uuidrequired
    • kindstringrequired
      One ofcodeautomatic
    • codestringrequirednullable
    • labelstringrequired
    • amountintegerrequired
  • taxLinesarray<object>required
    Each item has 4 fields
    • namestringrequired
    • amountintegerrequired
    • inclusivebooleanrequired
    • rateBpsinteger
  • shippingobjectrequirednullable
    Fields: 2 fields
    • optionIdstringrequired
    • amountintegerrequired
  • customermap<string, any>required
  • upsellsmap<string, string>required
  • expiresAtstringrequired
  • createdAtstringrequired
Request · cURL
curl -X GET "$GIEP_API_URL/v1/checkout-sessions/39fe7959-5f08-4461-aad8-55a67669" \
  -H "Authorization: Bearer $GIEP_API_KEY"
{
  "id": "37386ae0-251d-4f38-a753-611e841d7",
  "checkoutId": "679010dc-dba5-41d2-a1d7-5b76-d95",
  "status": "paid",
  "currency": "USD",
  "subtotal": 4999,
  "total": 4999,
  "paymentId": "a7c488a4-4db8-4274-ad74-a9a8-710",
  "orderId": "f6d8263a-f9f3-46d4-addf-b7d26ffc",
  "externalOrderRef": "1042",
  "acceptedBumpIds": [
    "bf43edde-3028-4d4a-a911-30a8-720"
  ],
  "discountCode": "string",
  "discounts": [
    {
      "discountId": "0be4e783-0872-408f-a8ca-2852-7b8",
      "kind": "code",
      "code": "string",
      "label": "string",
      "amount": 4999
    }
  ],
  "taxLines": [
    {
      "name": "string",
      "amount": 4999,
      "inclusive": false,
      "rateBps": 1
    }
  ],
  "shipping": {
    "optionId": "string",
    "amount": 4999
  },
  "customer": {},
  "upsells": {},
  "expiresAt": "2026-10-26T12:00:00.000Z",
  "createdAt": "2026-10-26T12:00:00.000Z"
}