Initiate checkout

Start a checkout for one product, then send the buyer to the url you get back. Full flow: Checkout.

POST

https://api.baag.cc/v1/checkout/sessions

Authorization

Use your public or secret key.

Authorization: Bearer pk_live_xxxxxxxxx

string

required

Bearer followed by your public or secret key.

Request Body

{
  "items": [
    {
      "product": "mw6",
      "size": "M",
      "color": "Red",
      "quantity": 2
    }
  ],
  "successUrl": "https://yoursite.com/thanks",
  "cancelUrl": "https://yoursite.com/cart",
  "customer": {
    "name": "Aline",
    "phone": "250788123456",
    "deliveryAddress": "Kicukiro"
  },
  "metadata": {
    "cartId": "abc123"
  }
}

object[]

required

Exactly one product for now.

Show item

string

required

The product’s slug.

string

A size from the product’s sizes, spelled exactly. Leave it out if the product has none.

string

A color name from the product’s colors, spelled exactly. Leave it out if the product has none.

integer

default:"1"

From 1 to 100.

string

required

Where the buyer lands after paying, with ?session_id=cs_… added. Must start with http:// or https://.

string

required

Where the buyer goes if they leave without paying. Must start with http:// or https://.

object

Pre-fills the checkout form. The buyer can still change it.

Show customer

string

Up to 100 characters.

string

Rwandan mobile number as 2507XXXXXXXX, no + or spaces.

string

Up to 500 characters.

object

Your own references, like a cart id. Up to 20 keys, string values up to 500 characters. Comes back untouched.

Response

Returned with status 201. Send the buyer to url.

{
  "id": "cs_q3Lw9vX2bTn8YkPz4RfA1sJd",
  "url": "https://checkout.baag.cc/cs_q3Lw9vX2bTn8YkPz4RfA1sJd",
  "status": "open",
  "items": [
    {
      "product": "mw6",
      "name": "Linen Shirt",
      "size": "M",
      "color": "Red",
      "quantity": 2
    }
  ],
  "successUrl": "https://yoursite.com/thanks",
  "cancelUrl": "https://yoursite.com/cart",
  "metadata": {
    "cartId": "abc123"
  },
  "expiresAt": "2026-10-09T10:30:00.000Z",
  "createdAt": "2026-10-09T10:00:00.000Z",
  "order": null
}

The session expires 30 minutes after it’s created.

Error Responses

Invalid request

Returned with status 400 when a field is missing or has a wrong value. The message names the field.

{
  "error": {
    "code": "invalid_request",
    "message": "successUrl: Invalid url"
  }
}

Variant not found

Returned with status 400 when the size and color don’t match a variant, or you sent them for a product that has none.

{
  "error": {
    "code": "variant_not_found",
    "message": "That size and color combination doesn't exist for this product. Check its variants."
  }
}

Product not found

Returned with status 404 when there’s no product with this slug in the store, or it’s archived.

{
  "error": {
    "code": "product_not_found",
    "message": "No product with the slug \"mw6\"."
  }
}

Sold out

Returned with status 409 when the product, or the size and color picked, is sold out.

{
  "error": {
    "code": "sold_out",
    "message": "Red / M is sold out."
  }
}

Insufficient stock

Returned with status 409 when the buyer asked for more than what’s left. The message says how many are left.

{
  "error": {
    "code": "insufficient_stock",
    "message": "Only 1 left in stock."
  }
}

Internal error

Returned with status 500 when something went wrong on Baag’s side. Retry.

{
  "error": {
    "code": "internal_error",
    "message": "Something went wrong on our side. Please try again."
  }
}

Key errors (401, 403, 429) are on API keys.

Get started

Store

Products

Collections

Checkout

Initiate checkout

Authorization

Request Body

Response

Error Responses

​Authorization

​Request Body

​Response

​Error Responses

Authorization

Request Body

Response

Error Responses