Public API v2: Buy X Get Y

Buy X Get Y offers: what the customer buys, what they get, and the discount on it.

Scopes	bogo:read, bogo:write
Plan	Plans with Buy X Get Y; otherwise 403
Takes effect	Saved in the app; reaches the storefront at the next upload.

Every response has the same envelope (success, status, data, meta; see Responses). Returns below describes data. The examples are real calls; the rules were created disabled.

Good to know

• get_max_uses caps how many times one cart gets the offer; null means no limit.

Buy X Get Y API endpoints

• GET/api/v2/bogo/rules# List rules
• POST/api/v2/bogo/rules# Create a rule
• GET/api/v2/bogo/rules/{id}# Get a rule
• PUT/api/v2/bogo/rules/{id}# Replace a rule
• DEL/api/v2/bogo/rules/{id}# Delete a rule
• POST/api/v2/bogo/rules/bulk-upsert# Create or replace rules in bulk
• POST/api/v2/bogo/rules/bulk-delete# Delete rules in bulk
• POST/api/v2/bogo/rules/upload# Upload rules to the storefront

The rule object

What every read returns. Lists come back as [] when empty, never null.

idstringread-only

Rule id.

namestring

Rule name.

priorityinteger

Lower number wins; see Rules.

statusenum

disabled rules are kept but not applied. One of disabled, enabled.

CustomersCommon object

Who gets the rule.

Show fields

apply_toenum

all everyone, logged in or not · logged_in any logged-in customer · non_logged_in visitors who are not logged in · customer_ids the listed customers · customer_tags customers with any of the tags · company_location the listed B2B company locations. Accepted here: all, logged_in, non_logged_in, customer_ids, customer_tags.

customer_ids[string]

Used when apply_to is customer_ids; required and not empty then.

customer_tags[string]

Used when apply_to is customer_tags; required and not empty then.

buy_typeenum

One of products, collections.

buy_product_ids[string]

buy_collection_ids[string]

buy_minimum_typeenum

One of quantity, amount.

buy_minimum_valuestring

get_typeenum

One of products, collections.

get_product_ids[string]

get_collection_ids[string]

get_quantityinteger or null

get_discount_typeenum

One of percentage, free.

get_discount_valuestring

get_max_usesinteger or null

ScheduleCommon object

When the rule applies.

Show fields

start_atstring

UTC date and time ending in Z; null or left out: starts at once.

end_atstring

After start_at; null or left out: never ends.

created_atstring or nullread-only

UTC, ending in Z.

updated_atstring or nullread-only

UTC, ending in Z.

The rule object

{
  "id": "7",
  "name": "Buy 2 get 1 half price",
  "priority": 1,
  "status": "disabled",
  "apply_to": "customer_tags",
  "customer_ids": [],
  "customer_tags": [
    "wholesale"
  ],
  "buy_type": "products",
  "buy_product_ids": [
    "8123456787001"
  ],
  "buy_collection_ids": [],
  "buy_minimum_type": "quantity",
  "buy_minimum_value": "2.00",
  "get_type": "products",
  "get_product_ids": [
    "8123456788001"
  ],
  "get_collection_ids": [],
  "get_quantity": 1,
  "get_discount_type": "percentage",
  "get_discount_value": "50.00",
  "get_max_uses": null,
  "start_at": "2026-11-01T00:00:00.000Z",
  "end_at": null,
  "created_at": "2026-10-21T09:34:18.000Z",
  "updated_at": "2026-10-21T09:34:18.000Z"
}

List rules

GET/api/v2/bogo/rules

Scope bogo:readCost 10

List rules, newest first.

Query parameters

limitinteger

1–250, default 50. See Paging.

cursorstring

next_cursor or prev_cursor of the last page; leave out for the first page. Keep the same filters on every page.

filter_statusenum

One of disabled, enabled.

filter_namestring

Part of the name, any case. 1–200 characters.

Returns

data[Rule]

The rules of this page; [] when there are none.

meta.paginationobject

limit, next_cursor, prev_cursor and links to the next and previous pages.

Request

cURL

curl -X GET "https://solution-public-api.bss-b2b.solutions/api/v2/bogo/rules?limit=2&filter_name=Buy" \
  -H "X-API-Key: $B2B_API_KEY" \
  -H "X-Shop-Domain: your-store.myshopify.com"

Response

200

{
  "success": true,
  "status": "success",
  "data": [
    {
      "id": "7",
      "name": "Buy 2 get 1 half price",
      "priority": 1,
      "status": "disabled",
      "apply_to": "customer_tags",
      "customer_ids": [],
      "customer_tags": [
        "wholesale"
      ],
      "buy_type": "products",
      "buy_product_ids": [
        "8123456787001"
      ],
      "buy_collection_ids": [],
      "buy_minimum_type": "quantity",
      "buy_minimum_value": "2.00",
      "get_type": "products",
      "get_product_ids": [
        "8123456788001"
      ],
      "get_collection_ids": [],
      "get_quantity": 1,
      "get_discount_type": "percentage",
      "get_discount_value": "50.00",
      "get_max_uses": null,
      "start_at": "2026-11-01T00:00:00.000Z",
      "end_at": null,
      "created_at": "2026-10-21T09:34:18.000Z",
      "updated_at": "2026-10-21T09:34:18.000Z"
    }
  ],
  "meta": {
    "timestamp": "2026-10-21T09:34:21.094Z",
    "version": "v2",
    "request_id": "d34a654e-3ec8-40f6-beae-2a319891ecfd",
    "rate_limit": {
      "cost": 10,
      "limit": 600,
      "remaining": 590,
      "restore_rate": 10
    },
    "pagination": {
      "limit": 2,
      "next_cursor": null,
      "prev_cursor": null,
      "links": {
        "self": "/api/v2/bogo/rules?limit=2&filter_name=Buy",
        "next": null,
        "prev": null
      }
    }
  }
}

Create a rule

POST/api/v2/bogo/rules

Scope bogo:writeCost 11

Create a rule.

The body of POST /rules, PUT /rules/{id} and each element of bulk-upsert (add id to replace a rule). PUT replaces the whole rule: optional fields left out go back to their defaults. Fields not listed here are refused with 422.

Arguments

namestringrequired

Rule name. 1–200 characters.

priorityintegerrequired

Lower number wins; see Rules. 0–99.

statusenumrequired

disabled rules are kept but not applied. One of disabled, enabled.

CustomersCommon objectrequired

Who gets the rule.

Show fields

apply_toenum

all everyone, logged in or not · logged_in any logged-in customer · non_logged_in visitors who are not logged in · customer_ids the listed customers · customer_tags customers with any of the tags · company_location the listed B2B company locations. Accepted here: all, logged_in, non_logged_in, customer_ids, customer_tags.

customer_ids[string]

Used when apply_to is customer_ids; required and not empty then.

customer_tags[string]

Used when apply_to is customer_tags; required and not empty then.

buy_typeenumrequired

One of products, collections.

buy_product_ids[string]

buy_collection_ids[string]

buy_minimum_typeenumrequired

• quantity, amount: The minimum is a number of items (whole number) or an amount.

buy_minimum_valuestringrequired

Greater than 0: a whole quantity, or an amount in the shop currency. Decimal string, up to 2 decimals.

get_typeenumrequired

One of products, collections.

get_product_ids[string]

get_collection_ids[string]

get_quantityintegerrequired

1–2,147,483,647.

get_discount_typeenumrequired

• percentage: A percentage off what they get (more than 0, at most 100).
• free: What they get is free.

get_discount_valuestring

A percentage, greater than 0 and at most 100. Left out, or "100", with free. Decimal string, up to 2 decimals.

get_max_usesinteger

How many times a cart gets the items; null or left out: no limit. 1–9,999,999,999.

ScheduleCommon object

When the rule applies.

Show fields

start_atstring

UTC date and time ending in Z; null or left out: starts at once.

end_atstring

After start_at; null or left out: never ends.

Returns

dataRule

The new rule.

Request

cURL

curl -X POST "https://solution-public-api.bss-b2b.solutions/api/v2/bogo/rules" \
  -H "X-API-Key: $B2B_API_KEY" \
  -H "X-Shop-Domain: your-store.myshopify.com" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Buy 2 get 1 half price",
  "priority": 1,
  "status": "disabled",
  "apply_to": "customer_tags",
  "customer_tags": [
    "wholesale"
  ],
  "buy_type": "products",
  "buy_product_ids": [
    "8123456787001"
  ],
  "buy_minimum_type": "quantity",
  "buy_minimum_value": "2",
  "get_type": "products",
  "get_product_ids": [
    "8123456788001"
  ],
  "get_quantity": 1,
  "get_discount_type": "percentage",
  "get_discount_value": "50",
  "start_at": "2026-11-01T00:00:00Z"
}'

Response

201

{
  "success": true,
  "status": "success",
  "data": {
    "id": "7",
    "name": "Buy 2 get 1 half price",
    "priority": 1,
    "status": "disabled",
    "apply_to": "customer_tags",
    "customer_ids": [],
    "customer_tags": [
      "wholesale"
    ],
    "buy_type": "products",
    "buy_product_ids": [
      "8123456787001"
    ],
    "buy_collection_ids": [],
    "buy_minimum_type": "quantity",
    "buy_minimum_value": "2.00",
    "get_type": "products",
    "get_product_ids": [
      "8123456788001"
    ],
    "get_collection_ids": [],
    "get_quantity": 1,
    "get_discount_type": "percentage",
    "get_discount_value": "50.00",
    "get_max_uses": null,
    "start_at": "2026-11-01T00:00:00.000Z",
    "end_at": null,
    "created_at": "2026-10-21T09:34:18.000Z",
    "updated_at": "2026-10-21T09:34:18.000Z"
  },
  "meta": {
    "timestamp": "2026-10-21T09:34:18.470Z",
    "version": "v2",
    "request_id": "5debfebd-4307-4d93-89cd-3146c5317a75",
    "rate_limit": {
      "cost": 11,
      "limit": 600,
      "remaining": 589,
      "restore_rate": 10
    }
  }
}

Get a rule

GET/api/v2/bogo/rules/{id}

Scope bogo:readCost 10

Get a rule.

Path parameters

idstringrequired

Rule id.

Returns

dataRule

The rule. An id that does not exist answers 404 RESOURCE_NOT_FOUND.

Request

cURL

curl -X GET "https://solution-public-api.bss-b2b.solutions/api/v2/bogo/rules/7" \
  -H "X-API-Key: $B2B_API_KEY" \
  -H "X-Shop-Domain: your-store.myshopify.com"

Response

200

{
  "success": true,
  "status": "success",
  "data": {
    "id": "7",
    "name": "Buy 2 get 1 half price",
    "priority": 1,
    "status": "disabled",
    "apply_to": "customer_tags",
    "customer_ids": [],
    "customer_tags": [
      "wholesale"
    ],
    "buy_type": "products",
    "buy_product_ids": [
      "8123456787001"
    ],
    "buy_collection_ids": [],
    "buy_minimum_type": "quantity",
    "buy_minimum_value": "2.00",
    "get_type": "products",
    "get_product_ids": [
      "8123456788001"
    ],
    "get_collection_ids": [],
    "get_quantity": 1,
    "get_discount_type": "percentage",
    "get_discount_value": "50.00",
    "get_max_uses": null,
    "start_at": "2026-11-01T00:00:00.000Z",
    "end_at": null,
    "created_at": "2026-10-21T09:34:18.000Z",
    "updated_at": "2026-10-21T09:34:18.000Z"
  },
  "meta": {
    "timestamp": "2026-10-21T09:34:19.783Z",
    "version": "v2",
    "request_id": "1d3952a0-7e05-4d6f-b92a-bc8d246ca3c6",
    "rate_limit": {
      "cost": 10,
      "limit": 600,
      "remaining": 590,
      "restore_rate": 10
    }
  }
}

Replace a rule

PUT/api/v2/bogo/rules/{id}

Scope bogo:writeCost 11

Replace a rule; optional fields left out go back to their defaults.

Path parameters

idstringrequired

Rule id.

Arguments

The same fields as Create a rule.

Returns

dataRule

The rule after the change.

Request

cURL

curl -X PUT "https://solution-public-api.bss-b2b.solutions/api/v2/bogo/rules/7" \
  -H "X-API-Key: $B2B_API_KEY" \
  -H "X-Shop-Domain: your-store.myshopify.com" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Buy 2 get 1 half price (updated)",
  "priority": 2,
  "status": "disabled",
  "apply_to": "customer_tags",
  "customer_tags": [
    "wholesale"
  ],
  "buy_type": "products",
  "buy_product_ids": [
    "8123456787001"
  ],
  "buy_minimum_type": "quantity",
  "buy_minimum_value": "2",
  "get_type": "products",
  "get_product_ids": [
    "8123456788001"
  ],
  "get_quantity": 1,
  "get_discount_type": "percentage",
  "get_discount_value": "50",
  "start_at": "2026-11-01T00:00:00Z"
}'

Response

200

{
  "success": true,
  "status": "success",
  "data": {
    "id": "7",
    "name": "Buy 2 get 1 half price (updated)",
    "priority": 2,
    "status": "disabled",
    "apply_to": "customer_tags",
    "customer_ids": [],
    "customer_tags": [
      "wholesale"
    ],
    "buy_type": "products",
    "buy_product_ids": [
      "8123456787001"
    ],
    "buy_collection_ids": [],
    "buy_minimum_type": "quantity",
    "buy_minimum_value": "2.00",
    "get_type": "products",
    "get_product_ids": [
      "8123456788001"
    ],
    "get_collection_ids": [],
    "get_quantity": 1,
    "get_discount_type": "percentage",
    "get_discount_value": "50.00",
    "get_max_uses": null,
    "start_at": "2026-11-01T00:00:00.000Z",
    "end_at": null,
    "created_at": "2026-10-21T09:34:18.000Z",
    "updated_at": "2026-10-21T09:34:22.000Z"
  },
  "meta": {
    "timestamp": "2026-10-21T09:34:22.411Z",
    "version": "v2",
    "request_id": "0281460a-1e13-4012-bb2c-545c945aae3a",
    "rate_limit": {
      "cost": 11,
      "limit": 600,
      "remaining": 589,
      "restore_rate": 10
    }
  }
}

Delete a rule

DEL/api/v2/bogo/rules/{id}

Scope bogo:writeCost 11

Delete a rule.

Path parameters

idstringrequired

Rule id.

Returns

data.idstring

Id of the deleted rule.

data.deletedboolean

true.

Request

cURL

curl -X DELETE "https://solution-public-api.bss-b2b.solutions/api/v2/bogo/rules/7" \
  -H "X-API-Key: $B2B_API_KEY" \
  -H "X-Shop-Domain: your-store.myshopify.com"

Response

200

{
  "success": true,
  "status": "success",
  "data": {
    "id": "7",
    "deleted": true
  },
  "meta": {
    "timestamp": "2026-10-21T09:34:26.345Z",
    "version": "v2",
    "request_id": "cc2e37ad-b9b3-4b3f-b1ca-ed9c6f4c3a74",
    "rate_limit": {
      "cost": 11,
      "limit": 600,
      "remaining": 589,
      "restore_rate": 10
    }
  }
}

Create or replace rules in bulk

POST/api/v2/bogo/rules/bulk-upsert

Scope bogo:writeCost ceil(10 + 0.4 × rules)

Create or replace up to 250 rules; each one succeeds or fails on its own.

See Bulk & idempotency.

Arguments

rules[object]required

1–250 rules, each with the fields of Create a rule.

Show fields

idstring

Set it to replace that rule, as Replace a rule does; leave it out to create one.

Returns

data.results[object]

One entry per rule, in the order sent.

Show fields

indexinteger

Position of the rule in rules.

idstring

Rule id.

resultenum

created, updated or error.

errorobject

code and message, only when result is error.

data.summaryobject

total, succeeded, failed.

Request

cURL

curl -X POST "https://solution-public-api.bss-b2b.solutions/api/v2/bogo/rules/bulk-upsert" \
  -H "X-API-Key: $B2B_API_KEY" \
  -H "X-Shop-Domain: your-store.myshopify.com" \
  -H "Content-Type: application/json" \
  -d '{
  "rules": [
    {
      "name": "Buy 2 get 1 half price B",
      "priority": 1,
      "status": "disabled",
      "apply_to": "customer_tags",
      "customer_tags": [
        "wholesale"
      ],
      "buy_type": "products",
      "buy_product_ids": [
        "8123456787001"
      ],
      "buy_minimum_type": "quantity",
      "buy_minimum_value": "2",
      "get_type": "products",
      "get_product_ids": [
        "8123456788001"
      ],
      "get_quantity": 1,
      "get_discount_type": "percentage",
      "get_discount_value": "50",
      "start_at": "2026-11-01T00:00:00Z"
    },
    {
      "name": "Buy 2 get 1 half price (bulk)",
      "priority": 1,
      "status": "disabled",
      "apply_to": "customer_tags",
      "customer_tags": [
        "wholesale"
      ],
      "buy_type": "products",
      "buy_product_ids": [
        "8123456787001"
      ],
      "buy_minimum_type": "quantity",
      "buy_minimum_value": "2",
      "get_type": "products",
      "get_product_ids": [
        "8123456788001"
      ],
      "get_quantity": 1,
      "get_discount_type": "percentage",
      "get_discount_value": "50",
      "start_at": "2026-11-01T00:00:00Z",
      "id": "7"
    }
  ]
}'

Response

200

{
  "success": true,
  "status": "success",
  "data": {
    "results": [
      {
        "index": 0,
        "id": "8",
        "result": "created"
      },
      {
        "index": 1,
        "id": "7",
        "result": "updated"
      }
    ],
    "summary": {
      "total": 2,
      "succeeded": 2,
      "failed": 0
    }
  },
  "meta": {
    "timestamp": "2026-10-21T09:34:23.729Z",
    "version": "v2",
    "request_id": "d7ad0f4c-4e15-4102-a5ec-9605d32ed3f9",
    "rate_limit": {
      "cost": 11,
      "limit": 600,
      "remaining": 589,
      "restore_rate": 10
    }
  }
}

Delete rules in bulk

POST/api/v2/bogo/rules/bulk-delete

Scope bogo:writeCost ceil(10 + 0.4 × rules)

Delete up to 250 rules; an unknown id fails on its own.

See Bulk & idempotency.

Arguments

ids[string]required

1–250 rule ids.

Returns

data.results[object]

One entry per id: index, id, result (deleted or error) and error (code, message) when it failed.

data.summaryobject

total, succeeded, failed.

Request

cURL

curl -X POST "https://solution-public-api.bss-b2b.solutions/api/v2/bogo/rules/bulk-delete" \
  -H "X-API-Key: $B2B_API_KEY" \
  -H "X-Shop-Domain: your-store.myshopify.com" \
  -H "Content-Type: application/json" \
  -d '{
  "ids": [
    "8",
    "999999999"
  ]
}'

Response

200

{
  "success": true,
  "status": "success",
  "data": {
    "results": [
      {
        "index": 0,
        "id": "8",
        "result": "deleted"
      },
      {
        "index": 1,
        "id": "999999999",
        "result": "error",
        "error": {
          "code": "RESOURCE_NOT_FOUND",
          "message": "Resource not found"
        }
      }
    ],
    "summary": {
      "total": 2,
      "succeeded": 1,
      "failed": 1
    }
  },
  "meta": {
    "timestamp": "2026-10-21T09:34:25.037Z",
    "version": "v2",
    "request_id": "44a67d6d-e5fe-4c37-bf97-bd5c6e6ba6dd",
    "rate_limit": {
      "cost": 11,
      "limit": 600,
      "remaining": 589,
      "restore_rate": 10
    }
  }
}

Upload rules to the storefront

POST/api/v2/bogo/rules/upload

Scope bogo:writeCost 20

Upload the rules to the storefront, as the app does.

The body is empty. See Upload.

Returns

data.statusenum

uploaded, or partial_success when some rules did not reach the storefront.

data.skippedobject

capacity_exceeded, write_failed and rule_id_range; see Upload.

Request

cURL

curl -X POST "https://solution-public-api.bss-b2b.solutions/api/v2/bogo/rules/upload" \
  -H "X-API-Key: $B2B_API_KEY" \
  -H "X-Shop-Domain: your-store.myshopify.com"

Response

Answer of the Net Terms upload; every module answers in this shape.

200

{
  "success": true,
  "status": "success",
  "data": {
    "status": "uploaded",
    "skipped": {
      "capacity_exceeded": 0,
      "write_failed": 0,
      "rule_id_range": null
    }
  },
  "meta": {
    "timestamp": "2026-10-21T09:34:46.663Z",
    "version": "v2",
    "request_id": "db2079e7-e134-412e-9943-e2c2b29a9e8c",
    "rate_limit": {
      "cost": 20,
      "limit": 600,
      "remaining": 580,
      "restore_rate": 10
    }
  }
}

Note

If you need further assistance, please feel free to reach us at [email protected] or Live Chat.