Purchase Intents

Purchase intents power Pages Buy links. Each one captures the product, the price, the quantity policy, optional expiry, and the usage rule that Pages should enforce before it creates an order. Use them when you want to publish a curated offer from your catalog instead of assembling a cart server-side.

The current Commerce SDKs do not yet expose first-class purchase-intent helpers, so the examples below call the HTTPS API directly in every language.

The purchase intent object

A purchase intent stores the commercial terms behind a Buy link together with the resolved product and price snapshots that Pages needs at checkout time. The object also carries derived lifecycle state such as whether the offer has been used, expired, or manually inactivated.

Properties

Name
activity
Type
object|null
Description
Recent Pages activity for this Buy link when tracking data is available. The nested recent array can include viewed, expired_viewed, payment_started, order_created, and payment_failed events.
Name
allow_variants
Type
boolean
Description
Whether Pages may switch between products in the linked variant set. This becomes true when the selected product participates in an active variant set that can be rendered as alternate options.
Name
application_id
Type
string
Description
Application that owns the Buy link configuration.
Name
created_at
Type
timestamp
Description
When the purchase intent was created.
Name
expires_at
Type
timestamp|null
Description
Optional timestamp after which the Buy link becomes unavailable to new shoppers.
Name
id
Type
string
Description
Unique purchase intent identifier with the sale_ prefix.
Name
inactive_at
Type
timestamp|null
Description
When the merchant explicitly inactivated the Buy link. When this is set, the intent is unavailable even if expires_at is still in the future.
Name
maximum_quantity
Type
integer
Description
Highest quantity a shopper may buy from this offer.
merchantobjectMerchant identity included when the intent is looked up through a public Buy link.Click or tap to expand
- Name
  app_id
  Type
  string
  Description
  Application identifier for the merchant.
- Name
  app_name
  Type
  string
  Description
  Human-readable application name.
- Name
  organization_id
  Type
  string
  Description
  Organization that owns the application.
- Name
  organization_name
  Type
  string
  Description
  Human-readable organization name.
Name
minimum_quantity
Type
integer
Description
Lowest quantity a shopper may buy from this offer.
Name
price
Type
object
Description
Resolved price configuration for the offer. The nested object includes active, optional id, optional label, nominal, and optional original strike-through pricing details.
Name
product
Type
object
Description
Resolved product snapshot for the offer. The nested object follows the Product shape and also includes variant_set_id when the offer is tied to a variant group.
Name
status
Type
enum
Description
Current effective state of the Buy link: active, expired, inactive, or used.
Name
updated_at
Type
timestamp|null
Description
When the merchant last changed the purchase intent.
usageobjectHow often the Buy link may be used.Click or tap to expand
- Name
  multi_use
  Type
  boolean
  Description
  When true, the same intent may produce multiple orders over time.
- Name
  order
  Type
  object
  Description
  Present after a single-use Buy link has already been consumed. Includes the resulting order ID and its creation time.
- Name
  single_use
  Type
  boolean
  Description
  When true, the first completed order consumes the Buy link.
Name
variant_set
Type
object|null
Description
Hydrated variant-set details when the offer can switch between related products. Includes the axes, the default product, and the active variant options that Pages may render.

Create a purchase intent

Create a Buy link configuration that points at a product and a price from your catalog. Commerce stores the offer, normalizes the usage rule, and returns the hydrated purchase intent you can hand off to Pages or your dashboard.

Rules

Send exactly one of product or product_id.
Send exactly one of price or price_id.
quantity.max must be greater than or equal to quantity.min.
expires_at must be a future RFC3339 timestamp when provided.
usage can mark the link as single_use or multi_use, but not both.

Request attributes

Name
expires_at
Type
timestamp
Description
Optional expiry time for the Buy link. After this moment, new shoppers can no longer create orders from the intent.
priceobjectInline price selection for the Buy link. Use this instead of price_id when you want to point at a nominal amount or override the original comparison price source.Click or tap to expand
- Name
  id
  Type
  string
  Description
  Existing price identifier to reuse.
- Name
  nominal
  Type
  object
  Description
  Inline amount when you are not reusing a stored price ID.
  View nominal attributesClick or tap to expand
  Name
  currency
  Type
  string
  Description
  Three-letter lowercase currency code.
  Name
  value
  Type
  integer
  Description
  Amount in the smallest currency unit.
- Name
  original
  Type
  object
  Description
  Optional original price for strike-through pricing when you are supplying a custom nominal amount.
  View original attributesClick or tap to expand
  Name
  id
  Type
  string
  Description
  Stored original price identifier.
  Name
  nominal
  Type
  object
  Description
  Inline original amount when you are not reusing a stored price ID.
  View nominal attributesClick or tap to expand
  Name
  currency
  Type
  string
  Description
  Three-letter lowercase currency code.
  Name
  value
  Type
  integer
  Description
  Amount in the smallest currency unit.
- Name
  original_id
  Type
  string
  Description
  Stored original price identifier when you want strike-through pricing without embedding original.
Name
price_id
Type
string
Description
Stored catalog price to reuse for the Buy link.
productobjectInline product selection for the Buy link. Use this instead of product_id when you need to pin the offer to a specific variant set member.Click or tap to expand
- Name
  id
  Type
  string
  Description
  Stored product identifier to sell through the Buy link.
- Name
  variant_set_id
  Type
  string
  Description
  Variant set identifier when the offer should allow shoppers to switch between related products.
Name
product_id
Type
string
Description
Stored catalog product to reuse for the Buy link.
quantityobjectQuantity bounds Pages should enforce.Click or tap to expand
- Name
  max
  Type
  integer
  Description
  Maximum quantity a shopper may buy.
- Name
  min
  Type
  integer
  Description
  Minimum quantity a shopper must buy.
usageobjectOptional usage policy. Omit it to create a reusable Buy link.Click or tap to expand
- Name
  multi_use
  Type
  boolean
  Description
  Allow the same intent to produce multiple orders.
- Name
  single_use
  Type
  boolean
  Description
  Consume the intent after the first completed order.

Request

POST

/purchase_intents/create

curl https://api.zebo.dev/purchase_intents/create       -H "Authorization: ******"       -H "Content-Type: application/json"       -d '{
    "product_id": "prod_P9sK3vLm4nQ2xR7tY1wBc8Da",
    "price_id": "pr_G6tV2nQ9xM4bR7cD1yKs5LpW",
    "quantity": {
      "max": 5,
      "min": 1
    },
    "usage": {
      "multi_use": true
    },
    "expires_at": "2026-12-01T09:00:00Z"
  }'

{
  "purchase_intent": {
    "id": "sale_B7tQ2nLm5yR8cV1pKs4Dx9Ha",
    "application_id": "app_6RrJ4mQ2vBc8Y1pNs5tW3LxD",
    "minimum_quantity": 1,
    "maximum_quantity": 5,
    "allow_variants": false,
    "usage": {
      "multi_use": true
    },
    "expires_at": "2026-12-01T09:00:00Z",
    "status": "active",
    "created_at": "2026-08-05T12:00:00Z",
    "product": {
      "id": "prod_P9sK3vLm4nQ2xR7tY1wBc8Da",
      "name": "Premium Matcha Tin",
      "type": "physical"
    },
    "price": {
      "id": "pr_G6tV2nQ9xM4bR7cD1yKs5LpW",
      "active": true,
      "nominal": {
        "currency": "ghs",
        "value": 18500
      }
    }
  }
}

Update a purchase intent

Update the mutable parts of a Buy link after creation. Product selection, price selection, and variant targeting stay fixed, but you can change the quantity bounds, move the expiry time, or reactivate an expired or canceled offer.

Rules

Send id to identify the purchase intent you want to update.
expires_at: null clears the expiry time.
reactivate: true clears an inactive_at timestamp and can also clear an already elapsed expiry.
When you send both quantity bounds, maximum_quantity must stay greater than or equal to minimum_quantity.

Request attributes

Name
expires_at
Type
timestamp|null
Description
New expiry time for the Buy link, or null to remove the current expiry.
Name
id
Type
string
Description
Purchase intent identifier. The API also accepts this field as purchase_intent_id.
Name
maximum_quantity
Type
integer
Description
New maximum quantity shoppers may buy.
Name
minimum_quantity
Type
integer
Description
New minimum quantity shoppers must buy.
Name
reactivate
Type
boolean
Description
Clear state that currently prevents new purchases.

Request

POST

/purchase_intents/update

curl https://api.zebo.dev/purchase_intents/update       -H "Authorization: ******"       -H "Content-Type: application/json"       -d '{
    "id": "sale_B7tQ2nLm5yR8cV1pKs4Dx9Ha",
    "minimum_quantity": 2,
    "maximum_quantity": 8,
    "reactivate": true
  }'

{
  "purchase_intent": {
    "id": "sale_B7tQ2nLm5yR8cV1pKs4Dx9Ha",
    "application_id": "app_6RrJ4mQ2vBc8Y1pNs5tW3LxD",
    "minimum_quantity": 2,
    "maximum_quantity": 8,
    "allow_variants": false,
    "usage": {
      "multi_use": true
    },
    "expires_at": "2026-12-01T09:00:00Z",
    "status": "active",
    "created_at": "2026-08-05T12:00:00Z",
    "updated_at": "2026-08-05T12:18:00Z",
    "product": {
      "id": "prod_P9sK3vLm4nQ2xR7tY1wBc8Da",
      "name": "Premium Matcha Tin",
      "type": "physical"
    },
    "price": {
      "id": "pr_G6tV2nQ9xM4bR7cD1yKs5LpW",
      "active": true,
      "nominal": {
        "currency": "ghs",
        "value": 18500
      }
    }
  }
}

Cancel a purchase intent

Cancel a Buy link so Pages stops creating new orders from it. Cancellation is merchant-driven and distinct from expiry: the offer is still visible in your records, but it becomes immediately unavailable to new shoppers.

Required attributes

Name
id
Type
string
Description
Purchase intent identifier. The API also accepts this field as purchase_intent_id.

Request

POST

/purchase_intents/cancel

curl https://api.zebo.dev/purchase_intents/cancel       -H "Authorization: ******"       -H "Content-Type: application/json"       -d '{
    "id": "sale_B7tQ2nLm5yR8cV1pKs4Dx9Ha"
  }'

{
  "purchase_intent": {
    "id": "sale_B7tQ2nLm5yR8cV1pKs4Dx9Ha",
    "application_id": "app_6RrJ4mQ2vBc8Y1pNs5tW3LxD",
    "minimum_quantity": 2,
    "maximum_quantity": 8,
    "allow_variants": false,
    "usage": {
      "multi_use": true
    },
    "expires_at": "2026-12-01T09:00:00Z",
    "inactive_at": "2026-08-05T12:26:00Z",
    "status": "inactive",
    "created_at": "2026-08-05T12:00:00Z",
    "updated_at": "2026-08-05T12:26:00Z"
  }
}

Lookup a purchase intent

Retrieve a Buy link by its opaque ID. Public Pages flows can call this endpoint without knowing the owning application_id, and authenticated dashboard callers receive the same hydrated object with merchant context, product details, and recent activity.

Required attributes

Name
id
Type
string
Description
Purchase intent identifier with the sale_ prefix.

Request

POST

/purchase_intents/lookup

curl https://api.zebo.dev/purchase_intents/lookup       -H "Content-Type: application/json"       -d '{
    "id": "sale_B7tQ2nLm5yR8cV1pKs4Dx9Ha"
  }'

{
  "purchase_intent": {
    "id": "sale_B7tQ2nLm5yR8cV1pKs4Dx9Ha",
    "application_id": "app_6RrJ4mQ2vBc8Y1pNs5tW3LxD",
    "merchant": {
      "app_id": "app_6RrJ4mQ2vBc8Y1pNs5tW3LxD",
      "app_name": "Tea House",
      "organization_id": "org_3Qn7Lp5cY2vR8tMd1Ks4BxWa",
      "organization_name": "Tea House Ltd"
    },
    "minimum_quantity": 1,
    "maximum_quantity": 5,
    "allow_variants": true,
    "usage": {
      "multi_use": true
    },
    "status": "active",
    "created_at": "2026-08-05T12:00:00Z",
    "product": {
      "id": "prod_P9sK3vLm4nQ2xR7tY1wBc8Da",
      "variant_set_id": "pg_1Ms9Qv4rLc7tY2pNd6Bx8HwK",
      "name": "Premium Matcha Tin",
      "type": "physical"
    },
    "price": {
      "id": "pr_G6tV2nQ9xM4bR7cD1yKs5LpW",
      "active": true,
      "nominal": {
        "currency": "ghs",
        "value": 18500
      }
    },
    "activity": {
      "recent": [
        {
          "id": "saleevt_9Mv2Qx6rLp1cY7tBd4Ks8HnW",
          "purchase_intent_id": "sale_B7tQ2nLm5yR8cV1pKs4Dx9Ha",
          "type": "viewed",
          "source": "pages_buy",
          "created_at": "2026-08-05T12:05:00Z"
        }
      ]
    }
  }
}

Page purchase intents

List the purchase intents owned by the authenticated application. Use this for dashboard views, back-office search, and Buy link audits.

Required attributes

Name
page_number
Type
integer
Description
1-based page number to fetch. Must be between 1 and 10 inclusive.
Name
page_size
Type
integer
Description
Number of items to return. Must be between 1 and 256 inclusive.

Request

POST

/purchase_intents/page

curl https://api.zebo.dev/purchase_intents/page       -H "Authorization: ******"       -H "Content-Type: application/json"       -d '{
    "page_number": 1,
    "page_size": 20
  }'

{
  "page": {
    "number": 1,
    "size": 20,
    "purchase_intents": [
      {
        "id": "sale_B7tQ2nLm5yR8cV1pKs4Dx9Ha",
        "application_id": "app_6RrJ4mQ2vBc8Y1pNs5tW3LxD",
        "minimum_quantity": 1,
        "maximum_quantity": 5,
        "allow_variants": false,
        "usage": {
          "multi_use": true
        },
        "status": "active",
        "created_at": "2026-08-05T12:00:00Z"
      },
      {
        "id": "sale_M4nQ7xVc2pLs8YtR1kDb5HwA",
        "application_id": "app_6RrJ4mQ2vBc8Y1pNs5tW3LxD",
        "minimum_quantity": 1,
        "maximum_quantity": 1,
        "allow_variants": false,
        "usage": {
          "single_use": true,
          "order": {
            "id": "or_9tW2xBc5pLm8Qn1Rr4Ks7YdV",
            "created_at": "2026-08-05T12:42:00Z"
          }
        },
        "status": "used",
        "created_at": "2026-08-04T17:20:00Z"
      }
    ]
  }
}

Create a product - Build the catalog item a Buy link points at.
Create a price - Store the catalog price a Buy link should reuse.
Accept payment with Zebo Checkout - Put the hosted checkout experience in front of customers.
Create an order - Compare direct order creation with Buy-link-driven order creation.

Purchase Intents

The purchase intent object

Properties

Create a purchase intent

Rules

Request attributes

Request

Update a purchase intent

Rules

Request attributes

Request

Cancel a purchase intent

Required attributes

Request

Lookup a purchase intent

Required attributes

Request

Page purchase intents

Required attributes

Request

Related resources