Inbound · Called from your POS

REST API Reference

Your POS calls BipBip. The API has two surfaces: Orders, to manage the lifecycle of what BipBip delivers to you via webhook, and Menu, to keep your catalog in sync — availability, prices and the brand's full menu. It is the counterpart of theWebhook Spec.

Surface	Prefix	What it does
Orders	/api/v1/Orders	Accept, reject, advance status, get and list.
Menu	/api/v1/menu	Availability, prices, per-entity edits and full catalog publishing.

Base URLs per environment

Production: https://merchant-api.bipbip.hn. Staging: https://merchant-api.bipbip.dev. Routes are prefixed with /api/v1/, versioned in the path.

Path casing

The contract publishes /api/v1/Orderswith a capital O and /api/v1/menuin lowercase. Use the exact casing documented on each endpoint below.

No public IP allowlist

BipBip does not publish a fixed IP allowlist in either direction — both outbound calls to BipBip and inbound webhooks travel over public TCP/443 with TLS. If your security policy requires a static allowlist or a private network path (e.g. AWS PrivateLink), contact [email protected] to arrange a custom setup for your tenant.

Authentication

Send theX-Bipbip-Api-Keyheader on every request, with the value the BipBip team gives you during onboarding. Each integrated merchant gets its own API Key, which identifies the client and scopes everything the API returns — orders, stores and brand.Mutations (POST/PUT/PATCH) additionally requireIdempotency-Key andX-Bipbip-Schema-Version(currently 1.0). To get your API Keys, email [email protected].

# Read — X-Bipbip-Api-Key only
curl -H "X-Bipbip-Api-Key: <api-key>" \
     https://merchant-api.bipbip.hn/api/v1/Orders/<orderKey>

# Mutation — add Idempotency-Key and X-Bipbip-Schema-Version
curl -X POST \
     -H "X-Bipbip-Api-Key: <api-key>" \
     -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
     -H "X-Bipbip-Schema-Version: 1.0" \
     -H "Content-Type: application/json" \
     -d '{}' \
     https://merchant-api.bipbip.hn/api/v1/Orders/<orderKey>/accept

Protecting the API Key

Never expose the API Key in the frontend, in public repositories or in client bundles. Keep it in server-side environment variables and never commit it.

Idempotency-Key

Every mutation — Orders and Menu alike — requires theIdempotency-Keyheader (UUID v4, unique per logical attempt) along withX-Bipbip-Schema-Version: 1.0. Responses are cached server-side for 24 hours.

Same key + same body within 24h → BipBip returns the original response without re-executing.
Same key + different body → HTTP 422 with a type ending in /idempotency-conflict.
New key → request processed normally.
Missing Idempotency-Key → HTTP 422.
Missing or unsupported X-Bipbip-Schema-Version → HTTP 400.

When to reuse the key and when to mint a new one

Reuse the same key when retrying the same logical attempt: timeout, 5xx, dropped connection. The server guarantees a single side effect. Mint a new key when a different logical attempt starts — for example, after a manual operator action.

{
  "type": "https://bipbip.app/probs/idempotency-conflict",
  "title": "Idempotency conflict",
  "detail": "Idempotency-Key reused with a different request body.",
  "status": 422,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

Rate limits

Limits apply per API Key and are active on every endpoint. When you exceed them, BipBip returns HTTP 429 with aRetry-Afterheader — the fix is exponential backoff with jitter on the client.

Window	Limit	Strategy
Fixed window	100 requests / min	Resets every 60s
Sliding window	1,000 requests / hour	Evaluated continuously

Errors

Every error response follows RFC 7807 Problem Details, with the fieldstype,title,detail,status,traceId andmeta. What meta carries depends on the error: transition 409s bringcurrentStatus and allowedTransitions[]; validation 422s bring errors, a map from field path to the list of rules it broke.

Discriminate on the type suffix, not on detail

detail is human-facing text and may change between versions. Thetype suffix is stable. Match withtype.endsWith('/invalid-state-transition') so you don't couple to the host, which varies across environments.

Status	Cause	What to do
400	Missing `X-Bipbip-Schema-Version`, or the value is not supported.	Add the header with value `1.0` to every mutation.
401	API Key missing, invalid or revoked.	Check `X-Bipbip-Api-Key`. If it was revoked, contact support.
404	The resource does not exist or does not belong to the authenticated client (order, store, menu code).	Confirm the exact identifier received via webhook or read.
409	Transition forbidden by the state machine, acceptance window expired, or bulk deactivation blocked on `PUT /menu`.	Read `meta.allowedTransitions[]` and pivot. Empty list = terminal state, do not retry.
422	Invalid body, missing `Idempotency-Key`, idempotency conflict, or a menu combo that is not shipped.	Inspect `meta.errors`. Do not retry without fixing the body.
429	Quota exceeded for the API Key.	Respect `Retry-After` and retry with backoff and jitter.
502 / 503	BackOffice did not respond or is unavailable. Only on the menu endpoints that delegate to it.	Retry with the same `Idempotency-Key` and backoff.

Generic error

{
  "type": "https://bipbip.app/probs/not-found",
  "title": "Order not found",
  "detail": "Order ord_xxx does not exist or does not belong to the authenticated client.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

Invalid transition (409)

{
  "type": "https://bipbip.app/probs/invalid-state-transition",
  "title": "Invalid state transition",
  "detail": "Cannot transition from 'Preparing' to 'HandedOver'.",
  "status": 409,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": {
    "currentStatus": "Preparing",
    "allowedTransitions": [
      "Ready"
    ]
  }
}

Validation error (422)

{
  "type": "https://bipbip.app/probs/validation",
  "title": "Validation failed",
  "detail": "One or more request fields are invalid.",
  "status": 422,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": {
    "errors": {
      "items[0].targetCode": [
        "The targetCode field is required."
      ]
    }
  }
}

Orders

Lifecycle of the orders BipBip delivers to you via webhook. Mutations requireX-Bipbip-Api-Key,X-Bipbip-Schema-Version andIdempotency-Key.

Statuses are read in PascalCase and written in snake_case

Reads (GET and the status field of every response) return Pending, Accepted,Preparing, Ready,HandedOver,Rejected, Cancelled. The PUT /status body, in contrast, acceptspreparing, ready andhanded_over. They are not the same vocabulary: do not compare thestatus you read against the one you write without normalizing.

POST/api/v1/Orders/{orderKey}/accept

Accept an order

Runs the atomic cascade Pending → Accepted → Preparing in a single operation. The order is never observable in Accepted from your POS: the response status is Preparing.

The acceptance window expires even while the order still reads Pending

BipBip validates the call against the expiresAt it published in the creation webhook. Past that instant, /accept returns409 with a type ending in/acceptance-timeout — even if GETstill shows the order as Pending. Readorder.expiresAt and don't accept out of window.

Key behavior

The response carries status: "Preparing" directly — Accepted is a non-observable intermediate step.
After /accept, do not call PUT /status with preparing: it returns 409.
Your POS's next action is ready when the order is done.
For auto-accept stores, BipBip runs the same cascade when it receives your webhook 200; expiresAt arrives as null.
Publishes the order.accepted_by_external_merchant.v1 event. The internal cascade to Preparing emits no extra event.

Path parameters

orderKeystringrequired

Opaque order identifier delivered by BipBip in the order.created webhook (format ord_ + 16 base62 characters).

Headers

X-Bipbip-Api-Keystringrequired

API Key issued by BipBip during onboarding.

X-Bipbip-Schema-Versionstringrequired

Schema version. Currently 1.0. Without it → 400.

Idempotency-KeyUUID v4required

Unique per logical attempt. Same key + same body within 24h → cached response. Same key + different body → 422.

Body

(empty)object

v1.0 — empty body: send a literal {}. The remoteOrderId was already bound when you replied to the order.created webhook, so do not include it here.

Returns — 202 Accepted

messagestring

Informational message. Its text may change without notice: for business logic use the HTTP status and data.

data.orderKeystring

Opaque order identifier (same as the path).

data.statusstring

Resulting status: "Preparing".

data.acceptedAtISO 8601

When the acceptance was recorded, per BipBip's clock.

data.remoteOrderIdstring | null

Your POS reference, already bound. It travels in every later webhook for this order.

# POST /api/v1/Orders/{orderKey}/accept
curl -X POST \
  -H "X-Bipbip-Api-Key: $API_KEY" \
  -H "X-Bipbip-Schema-Version: 1.0" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://merchant-api.bipbip.hn/api/v1/Orders/ord_oOR7xSbWz0QksS2I/accept

await fetch(`${BASE}/api/v1/Orders/${orderKey}/accept`, {
  method: 'POST',
  headers: {
    'X-Bipbip-Api-Key': process.env.BIPBIP_API_KEY,
    'X-Bipbip-Schema-Version': '1.0',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

Response

{
  "message": "Operación completada exitosamente",
  "data": {
    "orderKey": "ord_oOR7xSbWz0QksS2I",
    "status": "Preparing",
    "acceptedAt": "2026-08-07T17:12:44Z",
    "remoteOrderId": "POS_001_ORDER_42"
  }
}

{
  "type": "https://bipbip.app/probs/missing-schema-version",
  "title": "Missing schema version",
  "detail": "The X-Bipbip-Schema-Version header is required on mutations.",
  "status": 400,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/invalid-api-key",
  "title": "Unauthorized",
  "detail": "API Key missing or invalid.",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/not-found",
  "title": "Order not found",
  "detail": "Order ord_xxx does not exist or does not belong to the authenticated client.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/acceptance-timeout",
  "title": "Acceptance window expired",
  "detail": "The acceptance deadline for this order passed at 2026-08-07T17:17:44Z.",
  "status": 409,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/validation",
  "title": "Validation failed",
  "detail": "One or more request fields are invalid.",
  "status": 422,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": {
    "errors": {
      "items[0].targetCode": [
        "The targetCode field is required."
      ]
    }
  }
}

{
  "type": "https://bipbip.app/probs/rate-limit-exceeded",
  "title": "Too many requests",
  "detail": "Request quota exceeded for this API Key.",
  "status": 429,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

POST/api/v1/Orders/{orderKey}/reject

Reject an order

Moves the order from Pending to Rejected (terminal state), persists the structured reason and cancels the acceptance timeout job.

An unknown reasonCode does not fail — it is normalized

If you send a value outside the catalog, the API does not return 422 — it normalizes it toSYSTEM_ISSUE and returns that indata.reason. A typo in the code does not surface as an error, it surfaces as a misclassified rejection metric. Compare it against what you sent.

Path parameters

orderKeystringrequired

Opaque order identifier.

Headers

X-Bipbip-Api-Keystringrequired

Merchant API Key.

X-Bipbip-Schema-Versionstringrequired

1.0

Idempotency-KeyUUID v4required

Unique per logical attempt.

Body

reasonCodeenumrequired

Rejection reason. Closed enum: STORE_CLOSED, OUT_OF_OPERATING_HOURS, ITEM_NOT_OFFERED, ITEM_OUT_OF_STOCK, PRICE_MISMATCH, SYSTEM_ISSUE.

messagestringoptional

Free-text detail for support. Not shown to the end customer.

Returns — 202 Accepted

data.orderKeystring

Opaque order identifier.

data.statusstring

Always "Rejected", which is terminal: the order accepts no further transitions.

data.rejectedAtISO 8601

When the rejection was recorded, per BipBip's clock.

data.reasonstring | null

The reasonCode that was applied. It may differ from what you sent if it fell outside the catalog.

# POST /api/v1/Orders/{orderKey}/reject
curl -X POST \
  -H "X-Bipbip-Api-Key: $API_KEY" \
  -H "X-Bipbip-Schema-Version: 1.0" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
       "reasonCode": "ITEM_OUT_OF_STOCK",
       "message": "Out of dough for large pizza"
     }' \
  https://merchant-api.bipbip.hn/api/v1/Orders/ord_oOR7xSbWz0QksS2I/reject

await fetch(`${BASE}/api/v1/Orders/${orderKey}/reject`, {
  method: 'POST',
  headers: {
    'X-Bipbip-Api-Key': process.env.BIPBIP_API_KEY,
    'X-Bipbip-Schema-Version': '1.0',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "reasonCode": "ITEM_OUT_OF_STOCK",
    "message": "Out of dough for large pizza"
  }),
});

Body

// The reason reaches the customer. message is for support only.
{
  "reasonCode": "ITEM_OUT_OF_STOCK",
  "message": "Sin masa para pizza grande"
}

// The order came in but the location is not operating.
{
  "reasonCode": "STORE_CLOSED"
}

// An unknown reasonCode does not fail: it normalizes to this one.
{
  "reasonCode": "SYSTEM_ISSUE",
  "message": "El POS no confirmó la orden a tiempo"
}

Response

{
  "message": "Operación completada exitosamente",
  "data": {
    "orderKey": "ord_oOR7xSbWz0QksS2I",
    "status": "Rejected",
    "rejectedAt": "2026-08-07T17:12:44Z",
    "reason": "ITEM_OUT_OF_STOCK"
  }
}

{
  "type": "https://bipbip.app/probs/missing-schema-version",
  "title": "Missing schema version",
  "detail": "The X-Bipbip-Schema-Version header is required on mutations.",
  "status": 400,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/invalid-api-key",
  "title": "Unauthorized",
  "detail": "API Key missing or invalid.",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/not-found",
  "title": "Order not found",
  "detail": "Order ord_xxx does not exist or does not belong to the authenticated client.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/invalid-state-transition",
  "title": "Invalid state transition",
  "detail": "Cannot transition from 'Preparing' to 'HandedOver'.",
  "status": 409,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": {
    "currentStatus": "Preparing",
    "allowedTransitions": [
      "Ready"
    ]
  }
}

{
  "type": "https://bipbip.app/probs/validation",
  "title": "Validation failed",
  "detail": "One or more request fields are invalid.",
  "status": 422,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": {
    "errors": {
      "items[0].targetCode": [
        "The targetCode field is required."
      ]
    }
  }
}

PUT/api/v1/Orders/{orderKey}/status

Advance status

Advances an already-accepted order to the next valid state: preparing → ready → handed_over. Forward transitions only.

Expected transition flow

After /accept the order is already in Preparing. From there:

preparing → ready
ready → handed_over

preparing remains in the enum for compatibility, but calling it after/accept returns 409.

Post-acceptance cancellations are not exposed in v1.0

The enum does not accept cancelled. Cancellations after acceptance originate inside BipBip — customer, operator, timeout or failed webhook — and reach your POS through thecancelled event of the PUT /events webhook. To cancel an already-accepted order, email[email protected].

Path parameters

orderKeystringrequired

Opaque order identifier.

Headers

X-Bipbip-Api-Keystringrequired

Merchant API Key.

X-Bipbip-Schema-Versionstringrequired

1.0

Idempotency-KeyUUID v4required

Unique per logical attempt.

Body

statusenumrequired

Target status in snake_case: preparing, ready or handed_over. A transition that is not allowed returns 409 with the valid targets in meta.allowedTransitions[].

ready does not depend on you alone: the driver can also mark it ready from their app, and that record advances the order. A 409 with meta.currentStatus: "Ready" is not an error — it is a state already reached. Continue with handed_over.

occurredAtISO 8601optional

When the change actually happened in your system — useful if you queue events and send them late. If omitted, BipBip uses its own clock. When supplied by the merchant, it is clamped to [now−24h, now+5min].

Returns — 202 Accepted

data.orderKeystring

Opaque order identifier.

data.statusstring

Resulting status after applying the transition.

data.changedAtISO 8601

When BipBip recorded the change. It may differ from the occurredAt you sent.

# PUT /api/v1/Orders/{orderKey}/status
curl -X PUT \
  -H "X-Bipbip-Api-Key: $API_KEY" \
  -H "X-Bipbip-Schema-Version: 1.0" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
       "status": "ready",
       "occurredAt": "2026-08-07T17:12:44Z"
     }' \
  https://merchant-api.bipbip.hn/api/v1/Orders/ord_oOR7xSbWz0QksS2I/status

await fetch(`${BASE}/api/v1/Orders/${orderKey}/status`, {
  method: 'PUT',
  headers: {
    'X-Bipbip-Api-Key': process.env.BIPBIP_API_KEY,
    'X-Bipbip-Schema-Version': '1.0',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "status": "ready",
    "occurredAt": "2026-08-07T17:12:44Z"
  }),
});

Body

// The kitchen is done; the order waits for the driver.
{
  "status": "ready"
}

// Terminal for the merchant: it has left the store.
{
  "status": "handed_over"
}

// occurredAt is accepted within [now-24h, now+5min]; outside it is clamped.
{
  "status": "ready",
  "occurredAt": "2026-08-07T17:04:00+00:00"
}

Response

{
  "message": "Operación completada exitosamente",
  "data": {
    "orderKey": "ord_oOR7xSbWz0QksS2I",
    "status": "Ready",
    "changedAt": "2026-08-07T17:12:51Z"
  }
}

{
  "type": "https://bipbip.app/probs/missing-schema-version",
  "title": "Missing schema version",
  "detail": "The X-Bipbip-Schema-Version header is required on mutations.",
  "status": 400,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/invalid-api-key",
  "title": "Unauthorized",
  "detail": "API Key missing or invalid.",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/not-found",
  "title": "Order not found",
  "detail": "Order ord_xxx does not exist or does not belong to the authenticated client.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/invalid-state-transition",
  "title": "Invalid state transition",
  "detail": "Cannot transition from 'Preparing' to 'HandedOver'.",
  "status": 409,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": {
    "currentStatus": "Preparing",
    "allowedTransitions": [
      "Ready"
    ]
  }
}

{
  "type": "https://bipbip.app/probs/validation",
  "title": "Validation failed",
  "detail": "One or more request fields are invalid.",
  "status": 422,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": {
    "errors": {
      "items[0].targetCode": [
        "The targetCode field is required."
      ]
    }
  }
}

GET/api/v1/Orders/{orderKey}

Get an order

Returns the current status, the timestamp of every transition, the change history and the full commercial content. Read-only: no Idempotency-Key required.

Use it to recover a webhook you could not process

The data.order object has the same shape as theorder.created webhook payload: items,payment, summary,charges, discounts andinvoice. The same parser serves both channels — if a webhook was dropped, you rebuild it from here with no new code.

Path parameters

orderKeystringrequired

Opaque order identifier.

Headers

X-Bipbip-Api-Keystringrequired

Merchant API Key.

Returns — 200 OK

data.orderKeystring

Public, opaque order identifier. It is the only id that travels in URLs and payloads.

data.storeIdinteger

BipBip's internal store id. To address a store, use your own storeRemoteId.

data.brandIdinteger

BipBip's internal id for the brand that owns the store.

data.statusenum

Current status in PascalCase: Pending, Accepted, Preparing, Ready, HandedOver, Rejected or Cancelled.

The driver is not a status. Whether one is assigned is told by driverAssignedAt, not by status.

data.merchantStatusReasonstring | null

Reason for the last status change, when whoever triggered it declared one.

data.remoteOrderIdstring | null

The order reference in your POS.

data.receivedAtISO 8601

When BipBip received the order. It anchors the acceptance window.

data.acceptedAt · rejectedAt · preparingAt · readyAtISO 8601 | null

Timestamps of each merchant transition. preparingAt usually matches acceptedAt because of the accept cascade.

data.driverAssignedAtISO 8601 | null

When a driver was assigned. It is cleared if the driver is released and the order goes back to pending reassignment.

data.handedOverAtISO 8601 | null

When you released the food: to the driver on delivery, to the customer on pickup. That is where your progress ends.

It can be null with the order already in HandedOver: that happens when you never reported the handover and BipBip closed the order once delivery was confirmed. In that case nobody knows when you released it. Do not use this field to detect that the order left — use status for that.

data.deliveredAtISO 8601 | null

Since when the customer has the order. On orders created from August 12, 2026 onwards, null = no confirmed delivery yet. Earlier ones return null permanently, even if they were delivered: the field shipped without backfilling the earlier rows. If you reconcile a period spanning that date, do not read that null as “not delivered”.

This is the field that tells “the driver picked it up, it is on its way” apart from “it arrived”: both look like HandedOver, because your progress as a merchant ends when you release the food. On delivery the driver confirms it and it is later than handedOverAt; on pickup it matches it, because you handed the order to the customer yourself.

data.cancelledAtISO 8601 | null

When it was cancelled. It can be populated after a delivery, because of a refund or an incident.

data.history[]array

Chronological trace of status changes, with the actor behind each one.

fromStatusstring | null

Previous status. null on the first item, when the order was created.

toStatusstring

Status it moved to.

changedAtISO 8601

When the change happened.

actorTypeenum

Who triggered it: merchant (you, through the API), customer, operator (BipBip operator), driver or system (acceptance timeout, delivery failure).

actorIdstring | null

Actor identifier where applicable. null for system.

reasonstring | null

Declared reason. Free text: do not parse it.

driverobject | null

Driver behind the transition. Present only on driver changes. This — not reason — is where you read it.

eventenum

driver_assigned (there is a driver), driver_reassigned (replaced, there is a new one) or driver_released (there is no driver anymore, wait for a reassignment).

codestring | null

Driver identifier, the same one BipBip uses when talking about them with people (e.g. BIP-01424). Use it to refer to a specific driver when contacting support. Falls back to the internal id when the driver has no code on file, and on rows predating the code travelling in this payload. Treat it as opaque: it is a label, not a number.

fullNamestring | null

Driver name.

previousCodestring | null

Who they replace, by the same criteria. Only on driver_reassigned.

data.orderobject | null

Commercial content of the order. Same shape as the order.created webhook. null only if the original snapshot could not be read.

displayCodestring

Human-readable order code, for support.

storeRemoteIdstring

The store code in your POS, the one you configured in BipBip.

currencystring

ISO 4217 currency for every amount.

createdAtISO 8601

When the order was created in BipBip.

expiresAtISO 8601 | null

Acceptance deadline. null for auto-accept stores.

fulfillmentobject

type (delivery | pickup), isExpress, prepareBy and, depending on the type, driverPickupAt or customerPickupAt.

customerobject | null

Customer name. Only on pickup, to call them at the counter; null on delivery for PII minimization.

paymentobject

methods[] (supports combining cash, card and bips), amountToCollect and changeFor.

summaryobject

Aggregate totals for reconciliation: subtotal, taxes, discounts, additionalCharges, grandTotal.

charges[] · discounts[]array

Itemized charges and discounts, each declaring who bills it (billedBy) or who absorbs it (fundedBy).

items[]array

Ordered products with code, remoteCode, quantity, unitPrice, tax, lineTotal, note and their modifierGroups[].

customerNotestring | null

Customer note for the whole order.

invoiceobject | null

taxId and businessName if the customer requested a tax invoice; null for final consumers.

Driver release — how it looks in `history`

The driver does not move the merchant's status, so assign, reassign and release all produce rows wherefromStatus == toStatus — the order stays where it was. Without looking at driver.event, a release looks like an assignment and you would believe the order still has a driver.

[
  {
    "fromStatus": "Ready",
    "toStatus": "Ready",
    "changedAt": "2026-08-07T17:20:10Z",
    "actorType": "operator",
    "actorId": "Daniel",
    "reason": "Released: driver BIP-01424 (manual_release)",
    "driver": {
      "event": "driver_released",
      "code": "BIP-01424",
      "fullName": "Juan Pérez"
    }
  },
  {
    "fromStatus": "Ready",
    "toStatus": "Ready",
    "changedAt": "2026-08-07T17:18:02Z",
    "actorType": "operator",
    "actorId": "Daniel",
    "reason": "Driver BIP-01424 asignado manualmente por operador Daniel",
    "driver": {
      "event": "driver_assigned",
      "code": "BIP-01424",
      "fullName": "Juan Pérez"
    }
  }
]

# GET /api/v1/Orders/{orderKey}
curl \
  -H "X-Bipbip-Api-Key: $API_KEY" \
  https://merchant-api.bipbip.hn/api/v1/Orders/ord_oOR7xSbWz0QksS2I

const res = await fetch(`${BASE}/api/v1/Orders/${orderKey}`, {
  method: 'GET',
  headers: { 'X-Bipbip-Api-Key': process.env.BIPBIP_API_KEY },
});
const { data } = await res.json();
// data.order has the same shape as the order.created webhook

Response

{
  "message": "Operación completada exitosamente",
  "data": {
    "orderKey": "ord_oOR7xSbWz0QksS2I",
    "storeId": 558,
    "brandId": 381,
    "status": "Preparing",
    "merchantStatusReason": null,
    "remoteOrderId": "POS_001_ORDER_42",
    "receivedAt": "2026-08-07T17:12:44Z",
    "acceptedAt": "2026-08-07T17:12:51Z",
    "rejectedAt": null,
    "preparingAt": "2026-08-07T17:12:51Z",
    "readyAt": null,
    "driverAssignedAt": null,
    "handedOverAt": null,
    "deliveredAt": null,
    "cancelledAt": null,
    "history": [
      {
        "fromStatus": "Accepted",
        "toStatus": "Preparing",
        "changedAt": "2026-08-07T17:12:51Z",
        "actorType": "merchant",
        "actorId": "2",
        "reason": "Transición automática a 'Preparing' luego de aceptar la orden."
      },
      {
        "fromStatus": "Pending",
        "toStatus": "Accepted",
        "changedAt": "2026-08-07T17:12:51Z",
        "actorType": "merchant",
        "actorId": "2"
      }
    ],
    "order": {
      "displayCode": "355156479",
      "storeRemoteId": "POS_TGU_001",
      "currency": "HNL",
      "createdAt": "2026-08-07T17:12:44+00:00",
      "expiresAt": "2026-08-07T17:17:44+00:00",
      "fulfillment": {
        "type": "delivery",
        "isExpress": false,
        "prepareBy": "2026-08-07T17:32:44+00:00",
        "driverPickupAt": "2026-08-07T17:37:44+00:00"
      },
      "customer": null,
      "payment": {
        "methods": [
          {
            "type": "cash",
            "amount": 267.75
          }
        ],
        "amountToCollect": 267.75,
        "changeFor": 300
      },
      "summary": {
        "subtotal": 205,
        "taxes": 27.75,
        "discounts": 0,
        "additionalCharges": 35,
        "grandTotal": 267.75
      },
      "charges": [
        {
          "code": "delivery_fee",
          "amount": 35,
          "billedBy": "bipbip"
        }
      ],
      "discounts": [],
      "items": [
        {
          "code": "a3f2c1a46d594e7b8a2c9f0e1d2b3c4d",
          "remoteCode": "BURG-DOBLE",
          "name": "Hamburguesa Doble BBQ",
          "quantity": 1,
          "unitPrice": 185,
          "tax": 27.75,
          "lineTotal": 232.75,
          "note": "Sin cebolla",
          "modifierGroups": [
            {
              "code": "b4e3d2c5f6a74b8c9d0e1f2a3b4c5d6e",
              "name": "Extras",
              "options": [
                {
                  "code": "c5f4e3d6a7b85c9d0e1f2a3b4c5d6e7f",
                  "remoteCode": "OPT-QUESO-EXTRA",
                  "name": "Queso extra",
                  "quantity": 1,
                  "unitPrice": 20
                }
              ]
            }
          ]
        }
      ],
      "customerNote": "Dejar en portería",
      "invoice": null
    }
  }
}

{
  "type": "https://bipbip.app/probs/invalid-api-key",
  "title": "Unauthorized",
  "detail": "API Key missing or invalid.",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/not-found",
  "title": "Order not found",
  "detail": "Order ord_xxx does not exist or does not belong to the authenticated client.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/rate-limit-exceeded",
  "title": "Too many requests",
  "detail": "Request quota exceeded for this API Key.",
  "status": 429,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

GET/api/v1/Orders

List orders

Lists the authenticated client's orders, sorted by order number descending, with opaque cursor pagination.

Headers

X-Bipbip-Api-Keystringrequired

Merchant API Key.

Query parameters

Cursorstringoptional

Opaque cursor returned in nextCursor by the previous response. Do not interpret or hand-build it.

PageSizeintegeroptional

Page size. Maximum 100, default 20.

Statusstringoptional

Filter by status, in the same vocabulary reads return: Pending, Accepted, Preparing, Ready, HandedOver, Rejected, Cancelled. There is no driver status to filter on.

FromDateISO 8601optional

Start of the date range.

ToDateISO 8601optional

End of the date range.

Returns — 200 OK

data.items[]array

Page of results, newest first.

orderKeystring

Opaque identifier. Use it in GET /api/v1/Orders/{orderKey} for the detail.

storeIdinteger

BipBip's internal store id.

statusenum

Current status, in PascalCase.

receivedAtISO 8601

When BipBip received the order. It is not the listing's sort criterion: it can differ from the real creation order, so the listing sorts by order number and the cursor is that same number.

acceptedAtISO 8601 | null

When you accepted it. null if it is still pending or you rejected it.

remoteOrderIdstring | null

The order reference in your POS.

driverAssignedAtISO 8601 | null

When a driver was assigned. null if there is none yet or the driver was released.

deliveredAtISO 8601 | null

Since when the customer has the order. Together with status it tells an in-transit order apart from a delivered one without fetching the detail. See the order detail for the full semantics.

data.nextCursorstring | null

Opaque cursor for the next page. null on the last page.

data.hasMoreboolean

The stop condition for your pagination loop.

# GET /api/v1/Orders — first page
curl \
  -H "X-Bipbip-Api-Key: $API_KEY" \
  "https://merchant-api.bipbip.hn/api/v1/Orders?Status=Preparing&PageSize=50"

const res = await fetch(`${BASE}/api/v1/Orders?${params}`, {
  method: 'GET',
  headers: { 'X-Bipbip-Api-Key': process.env.BIPBIP_API_KEY },
});
const { data } = await res.json();
// data.hasMore === true → repeat with ?Cursor=data.nextCursor

Response

{
  "message": "Operación completada exitosamente",
  "data": {
    "items": [
      {
        "orderKey": "ord_oOR7xSbWz0QksS2I",
        "storeId": 558,
        "status": "Preparing",
        "receivedAt": "2026-08-07T17:12:44Z",
        "acceptedAt": "2026-08-07T17:12:51Z",
        "remoteOrderId": "POS_001_ORDER_42",
        "driverAssignedAt": null,
        "deliveredAt": null
      }
    ],
    "nextCursor": "eyJsYXN0SWQiOjE3fQ",
    "hasMore": true
  }
}

{
  "type": "https://bipbip.app/probs/invalid-api-key",
  "title": "Unauthorized",
  "detail": "API Key missing or invalid.",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/validation",
  "title": "Validation failed",
  "detail": "One or more request fields are invalid.",
  "status": 422,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": {
    "errors": {
      "items[0].targetCode": [
        "The targetCode field is required."
      ]
    }
  }
}

{
  "type": "https://bipbip.app/probs/rate-limit-exceeded",
  "title": "Too many requests",
  "detail": "Request quota exceeded for this API Key.",
  "status": 429,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

State machine — what the merchant transitions

From the REST API the merchant triggers these transitions:Pending →Preparing (via /accept, which passes through Accepted automatically) orRejected (via /reject);Preparing →Ready →HandedOver (via PUT /status).

The Cancelled state is set by BipBip and reaches your POS via webhook — the merchant does NOT transition it from the REST API.

Driver assignment is not a status. BipBip notifies it with thedriver_assigned event of thePUT /events webhook and records it indriverAssignedAt, but the order'sstatus does not move: it stays where it was until you advance it. The driver cycle runs in parallel, so that event can arrive even while the order is inPreparing, before you reportready.

Inbound · Catalog sync

Scope	What it touches	`stores` field
store	An override on one or more stores, on top of the master catalog. Reversible and visible in the store menu read.	Required. This is the default when `scope` is omitted.
brand	Edits the brand's master catalog: it affects every store of that brand.	Must be omitted.

Check /menu/capabilities before writing

Only the (entity, field, scope) combinations actually shipped are accepted. A deferred combo does not appear in the matrix and the validator rejects it with422. If you are building integrations on new fields, read the matrix first instead of assuming.

Writes are asynchronous — except two

The ten per-entity write endpoints return 202 Accepted with achangeId. Keep it: it is the only way to check the outcome inGET /menu/changes/{changeId}and to correlate the menu.change.completed.v1 webhook.

The exceptions are POST /menu/preview(read-only) and PUT /menu, which issynchronous: its 200 already reflects what was applied.

A 202 does not mean it was applied

The real outcome is per store. A global status: "Applied"can coexist with failed rows: each store is applied independently. Walkresults[] and check applied on every row — the global status is not enough.

PUT/api/v1/menu/availability

Change availability

Write shortcut over product or modifierOption in store scope. Each item is applied to every store listed in stores.

Headers

X-Bipbip-Api-Keystringrequired

Merchant API Key.

X-Bipbip-Schema-Versionstringrequired

1.0

Idempotency-KeyUUID v4required

Unique per logical attempt.

Body

stores[]array<string>required

Target stores, by your remoteId. The change applies to all of them, and they must belong to a single brand.

items[]arrayrequired

Items with their target availability.

targetEntityenumrequired

product or modifierOption.

targetCodestringrequired

Target entity code — your remoteCode.

availablebooleanrequired

true = visible/orderable; false = hidden/sold out.

categoryCodestringoptional

Disambiguates the entity when its code is not unique. For modifierOption it is the parent group code.

Returns — 202 Accepted

data.changeIdstring

Change identifier (chg_ + 16 characters). Keep it to check the outcome.

# PUT /api/v1/menu/availability
curl -X PUT \
  -H "X-Bipbip-Api-Key: $API_KEY" \
  -H "X-Bipbip-Schema-Version: 1.0" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
       "stores": [
         "POS_TGU_001",
         "POS_SPS_004"
       ],
       "items": [
         {
           "targetEntity": "product",
           "targetCode": "BURG-DOBLE",
           "available": false
         },
         {
           "targetEntity": "modifierOption",
           "targetCode": "OPT-QUESO-EXTRA",
           "available": true,
           "categoryCode": "GRP-EXTRAS"
         }
       ]
     }' \
  https://merchant-api.bipbip.hn/api/v1/menu/availability

await fetch(`${BASE}/api/v1/menu/availability`, {
  method: 'PUT',
  headers: {
    'X-Bipbip-Api-Key': process.env.BIPBIP_API_KEY,
    'X-Bipbip-Schema-Version': '1.0',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "stores": [
      "POS_TGU_001",
      "POS_SPS_004"
    ],
    "items": [
      {
        "targetEntity": "product",
        "targetCode": "BURG-DOBLE",
        "available": false
      },
      {
        "targetEntity": "modifierOption",
        "targetCode": "OPT-QUESO-EXTRA",
        "available": true,
        "categoryCode": "GRP-EXTRAS"
      }
    ]
  }),
});

Body

// It does not come back on its own: reactivate it with available: true.
{
  "stores": [
    "POS_TGU_001"
  ],
  "items": [
    {
      "targetEntity": "product",
      "targetCode": "BURG-DOBLE",
      "available": false
    }
  ]
}

// Turns off the option, not the product. categoryCode is the parent group.
{
  "stores": [
    "POS_TGU_001"
  ],
  "items": [
    {
      "targetEntity": "modifierOption",
      "targetCode": "OPT-QUESO-EXTRA",
      "available": false,
      "categoryCode": "GRP-EXTRAS"
    }
  ]
}

// Best-effort per store: check results[] in GET /menu/changes/{changeId}.
{
  "stores": [
    "POS_TGU_001",
    "POS_SPS_004",
    "POS_CEIBA_002"
  ],
  "items": [
    {
      "targetEntity": "product",
      "targetCode": "BURG-DOBLE",
      "available": false
    }
  ]
}

// The code to send comes from overrides[] in GET /menu/stores/{storeRemoteId}.
{
  "stores": [
    "POS_TGU_001"
  ],
  "items": [
    {
      "targetEntity": "product",
      "targetCode": "BURG-DOBLE",
      "available": true
    },
    {
      "targetEntity": "modifierOption",
      "targetCode": "OPT-QUESO-EXTRA",
      "available": true,
      "categoryCode": "GRP-EXTRAS"
    }
  ]
}

Response

{
  "message": "Operación completada exitosamente",
  "data": {
    "changeId": "chg_9fA2kQ7pLm3XbT10"
  }
}

{
  "type": "https://bipbip.app/probs/missing-schema-version",
  "title": "Missing schema version",
  "detail": "The X-Bipbip-Schema-Version header is required on mutations.",
  "status": 400,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/invalid-api-key",
  "title": "Unauthorized",
  "detail": "API Key missing or invalid.",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/not-found",
  "title": "Order not found",
  "detail": "Order ord_xxx does not exist or does not belong to the authenticated client.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/validation",
  "title": "Validation failed",
  "detail": "One or more request fields are invalid.",
  "status": 422,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": {
    "errors": {
      "items[0].targetCode": [
        "The targetCode field is required."
      ]
    }
  }
}

{
  "type": "https://bipbip.app/probs/rate-limit-exceeded",
  "title": "Too many requests",
  "detail": "Request quota exceeded for this API Key.",
  "status": 429,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

PUT/api/v1/menu/prices

Change prices

Price write shortcut for product or modifierOption. Store scope only: the price replaces the master catalog price for the listed stores alone.

Body

stores[]array<string>required

Target stores, by your remoteId.

items[]arrayrequired

Items with their override price.

targetEntityenumrequired

product or modifierOption.

targetCodestringrequired

Target entity code.

pricenumberrequired

Store override price. Must be greater than or equal to 0.

categoryCodestringoptional

Disambiguates the entity when its code is not unique.

Returns — 202 Accepted

data.changeIdstring

Change identifier.

# PUT /api/v1/menu/prices
curl -X PUT \
  -H "X-Bipbip-Api-Key: $API_KEY" \
  -H "X-Bipbip-Schema-Version: 1.0" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
       "stores": [
         "POS_TGU_001"
       ],
       "items": [
         {
           "targetEntity": "product",
           "targetCode": "BURG-DOBLE",
           "price": 185
         }
       ]
     }' \
  https://merchant-api.bipbip.hn/api/v1/menu/prices

await fetch(`${BASE}/api/v1/menu/prices`, {
  method: 'PUT',
  headers: {
    'X-Bipbip-Api-Key': process.env.BIPBIP_API_KEY,
    'X-Bipbip-Schema-Version': '1.0',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "stores": [
      "POS_TGU_001"
    ],
    "items": [
      {
        "targetEntity": "product",
        "targetCode": "BURG-DOBLE",
        "price": 185
      }
    ]
  }),
});

Body

// Does not touch the master catalog. The previous value shows up as base on read.
{
  "stores": [
    "POS_TGU_001"
  ],
  "items": [
    {
      "targetEntity": "product",
      "targetCode": "BURG-DOBLE",
      "price": 185
    }
  ]
}

// Same mechanism, at option level.
{
  "stores": [
    "POS_TGU_001"
  ],
  "items": [
    {
      "targetEntity": "modifierOption",
      "targetCode": "OPT-QUESO-EXTRA",
      "price": 22,
      "categoryCode": "GRP-EXTRAS"
    }
  ]
}

Response

{
  "message": "Operación completada exitosamente",
  "data": {
    "changeId": "chg_9fA2kQ7pLm3XbT10"
  }
}

{
  "type": "https://bipbip.app/probs/missing-schema-version",
  "title": "Missing schema version",
  "detail": "The X-Bipbip-Schema-Version header is required on mutations.",
  "status": 400,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/invalid-api-key",
  "title": "Unauthorized",
  "detail": "API Key missing or invalid.",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/not-found",
  "title": "Order not found",
  "detail": "Order ord_xxx does not exist or does not belong to the authenticated client.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/validation",
  "title": "Validation failed",
  "detail": "One or more request fields are invalid.",
  "status": 422,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": {
    "errors": {
      "items[0].targetCode": [
        "The targetCode field is required."
      ]
    }
  }
}

PATCH/api/v1/menu/products/{code}

Modify a product

Edits product fields by code. With store scope it applies a per-store override; with brand scope it modifies the brand's master catalog.

What each scope can edit

store: available, price, name, description, schedule, channels.
brand: price, name, description, tax, maxPerOrder, image. available is deferred in this scope: it is a per-store override concept.

The image is re-hosted, not passed through

image takes an http(s) URL of yours. BipBip downloads it, converts it to WebP and re-hosts it in its own bucket, so the read returns a different URL. The202 does not mean the final image is available yet. If the URL is not reachable, is not an image, or exceeds the maximum size, the change is rejected with422 before being emitted.

Path parameters

codestringrequired

Product code — the same one the store menu read returns.

Body

scopeenumoptional

store (default) or brand.

stores[]array<string>

Target stores. Required in store scope; must be omitted in brand scope.

categoryCodestringoptional

Disambiguates when the same product code repeats across menu categories.

setobjectrequired

Declarative field set. Every property absent or null means "no change".

availableboolean

Availability at the store. store scope only.

pricenumber

Must be greater than or equal to 0.

name · descriptionstring

Product name and description.

scheduleobject

Availability window: days[] as three-letter codes (mon…sun, case-insensitive, at least one), startTime and endTime in HH:mm. Outside the window the item is unavailable.

channels[]array<string>

delivery and/or pickup (case-insensitive). An unknown value is rejected with 422. Empty list = the item applies to no channel.

taxnumber

Tax as a fraction (e.g. 0.15). Between 0 and 1. brand scope only.

maxPerOrderinteger

Maximum units per order, greater than 0. brand scope only.

imagestring

Absolute http(s) image URL. brand scope only.

# PATCH /api/v1/menu/products/{code} — store scope
curl -X PATCH \
  -H "X-Bipbip-Api-Key: $API_KEY" \
  -H "X-Bipbip-Schema-Version: 1.0" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
       "stores": [
         "POS_TGU_001"
       ],
       "set": {
         "price": 185,
         "name": "Hamburguesa Doble BBQ",
         "schedule": {
           "days": [
             "mon",
             "tue"
           ],
           "startTime": "18:00",
           "endTime": "23:00"
         },
         "channels": [
           "delivery"
         ]
       },
       "scope": "store"
     }' \
  https://merchant-api.bipbip.hn/api/v1/menu/products/BURG-DOBLE

# PATCH /api/v1/menu/products/{code} — brand scope (omit stores)
curl -X PATCH \
  -H "X-Bipbip-Api-Key: $API_KEY" \
  -H "X-Bipbip-Schema-Version: 1.0" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
       "set": {
         "price": 175,
         "description": "Double patty, bacon and house BBQ sauce",
         "tax": 0.15,
         "maxPerOrder": 10,
         "image": "https://cdn.your-merchant.com/burg-doble.jpg"
       },
       "scope": "brand"
     }' \
  https://merchant-api.bipbip.hn/api/v1/menu/products/BURG-DOBLE

Body

// Only the fields present are applied. A reversible override on that store.
{
  "stores": [
    "POS_TGU_001"
  ],
  "set": {
    "price": 185
  },
  "scope": "store"
}

// Outside the window it reads orderable: false with a resumesAt: it returns on its own.
{
  "stores": [
    "POS_TGU_001"
  ],
  "set": {
    "schedule": {
      "days": [
        "mon",
        "wed",
        "fri"
      ],
      "startTime": "18:00",
      "endTime": "23:00"
    }
  },
  "scope": "store"
}

// Still orderable, but restricted. An empty list does not lift the restriction.
{
  "stores": [
    "POS_TGU_001"
  ],
  "set": {
    "channels": [
      "delivery"
    ]
  },
  "scope": "store"
}

// Rewrites the base value for every store. That is why stores is omitted.
{
  "set": {
    "price": 175,
    "name": "Hamburguesa Doble BBQ",
    "description": "Doble carne, tocino y salsa BBQ"
  },
  "scope": "brand"
}

Response

{
  "message": "Operación completada exitosamente",
  "data": {
    "changeId": "chg_9fA2kQ7pLm3XbT10"
  }
}

{
  "type": "https://bipbip.app/probs/missing-schema-version",
  "title": "Missing schema version",
  "detail": "The X-Bipbip-Schema-Version header is required on mutations.",
  "status": 400,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/invalid-api-key",
  "title": "Unauthorized",
  "detail": "API Key missing or invalid.",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/not-found",
  "title": "Order not found",
  "detail": "Order ord_xxx does not exist or does not belong to the authenticated client.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/validation",
  "title": "Validation failed",
  "detail": "One or more request fields are invalid.",
  "status": 422,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": {
    "errors": {
      "items[0].targetCode": [
        "The targetCode field is required."
      ]
    }
  }
}

PATCH/api/v1/menu/modifier-options/{code}

Modify a modifier option

Edits option fields by code. Store scope for per-store overrides; brand scope for the master catalog.

In brand scope, categoryCode is required

And it is not a menu category: it is the code of the parent modifier group. Option codes are not unique across groups, so without it there is no way to resolve which option to edit.

Per-store price and name do not reach the customer app yet

In store scope, price andname are accepted and persisted, but are not yet reflected in the customer app. This is the case /menu/capabilities flags withpendingCustomerRollout: true.

Path parameters

codestringrequired

Modifier option code.

Body

scopeenumoptional

store (default) or brand. In brand scope it applies to Domicilio only (delivery/pickup).

stores[]array<string>

Required in store scope; omitted in brand.

categoryCodestring

Code of the parent modifier group. Optional in store scope, required in brand.

set.availableboolean

store scope only.

set.price · set.namenumber · string

Editable in both scopes. In store, with pendingCustomerRollout.

set.isDefaultboolean

Marks the option as preselected. brand scope only.

set.maxPerOrderinteger

Per-order unit cap, greater than 0. brand scope only.

# PATCH /api/v1/menu/modifier-options/{code}
curl -X PATCH \
  -H "X-Bipbip-Api-Key: $API_KEY" \
  -H "X-Bipbip-Schema-Version: 1.0" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
       "stores": [
         "POS_TGU_001"
       ],
       "set": {
         "available": false,
         "price": 25
       },
       "categoryCode": "GRP-EXTRAS",
       "scope": "store"
     }' \
  https://merchant-api.bipbip.hn/api/v1/menu/modifier-options/OPT-QUESO-EXTRA

await fetch(`${BASE}/api/v1/menu/modifier-options/${code}`, {
  method: 'PATCH',
  headers: {
    'X-Bipbip-Api-Key': process.env.BIPBIP_API_KEY,
    'X-Bipbip-Schema-Version': '1.0',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "stores": [
      "POS_TGU_001"
    ],
    "set": {
      "available": false,
      "price": 25
    },
    "categoryCode": "GRP-EXTRAS",
    "scope": "store"
  }),
});

Body

// A reversible override on that store.
{
  "stores": [
    "POS_TGU_001"
  ],
  "set": {
    "price": 22
  },
  "categoryCode": "GRP-EXTRAS",
  "scope": "store"
}

// Here categoryCode is required: option codes repeat across groups.
{
  "set": {
    "price": 20,
    "name": "Queso extra"
  },
  "categoryCode": "GRP-EXTRAS",
  "scope": "brand"
}

Response

{
  "message": "Operación completada exitosamente",
  "data": {
    "changeId": "chg_9fA2kQ7pLm3XbT10"
  }
}

{
  "type": "https://bipbip.app/probs/invalid-api-key",
  "title": "Unauthorized",
  "detail": "API Key missing or invalid.",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/not-found",
  "title": "Order not found",
  "detail": "Order ord_xxx does not exist or does not belong to the authenticated client.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/validation",
  "title": "Validation failed",
  "detail": "One or more request fields are invalid.",
  "status": 422,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": {
    "errors": {
      "items[0].targetCode": [
        "The targetCode field is required."
      ]
    }
  }
}

PATCH/api/v1/menu/categories/{code}

Modify a category

Edits the name and position of a category in the brand's master catalog. Brand scope only for now.

Brand-only, and the code is BipBip's

Categories have no per-store override: stores must be omitted. Thecode in the path is the one BipBip assigns and the menu read returns — theremoteCode you sent when publishing the full menu isnot preserved for categories. Keep that mapping on your side if you need it.

Path parameters

codestringrequired

Category code assigned by BipBip.

Body

scopeenumrequired

brand. Omit stores.

set.namestring

Visible category name.

set.positioninteger

Sort position within the menu. Greater than or equal to 0.

# PATCH /api/v1/menu/categories/{code} — brand scope only
curl -X PATCH \
  -H "X-Bipbip-Api-Key: $API_KEY" \
  -H "X-Bipbip-Schema-Version: 1.0" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
       "set": {
         "name": "Burgers",
         "position": 1
       },
       "scope": "brand"
     }' \
  https://merchant-api.bipbip.hn/api/v1/menu/categories/CAT-HAMBURGUESAS

await fetch(`${BASE}/api/v1/menu/categories/${code}`, {
  method: 'PATCH',
  headers: {
    'X-Bipbip-Api-Key': process.env.BIPBIP_API_KEY,
    'X-Bipbip-Schema-Version': '1.0',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "set": {
      "name": "Burgers",
      "position": 1
    },
    "scope": "brand"
  }),
});

Response

{
  "message": "Operación completada exitosamente",
  "data": {
    "changeId": "chg_9fA2kQ7pLm3XbT10"
  }
}

{
  "type": "https://bipbip.app/probs/invalid-api-key",
  "title": "Unauthorized",
  "detail": "API Key missing or invalid.",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/not-found",
  "title": "Order not found",
  "detail": "Order ord_xxx does not exist or does not belong to the authenticated client.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/validation",
  "title": "Validation failed",
  "detail": "One or more request fields are invalid.",
  "status": 422,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": {
    "errors": {
      "items[0].targetCode": [
        "The targetCode field is required."
      ]
    }
  }
}

PATCH/api/v1/menu/modifiers/{code}

Modify a modifier group

Edits the name, minimum, maximum and selection type of a group in the master catalog. Brand scope only for now.

Same code rule as categories

The code in the path is the one BipBip assigns. TheremoteCode from the full-menu submission is not preserved for groups.

Path parameters

codestringrequired

Modifier group code assigned by BipBip.

Body

scopeenumrequired

brand. Omit stores.

set.namestring

Visible group name.

set.mininteger

Minimum selections. Greater than or equal to 0.

set.maxinteger

Maximum selections. Greater than or equal to 1 and greater than or equal to min.

set.typeenum

radio (single selection) or checkbox (multiple), case-insensitive. An unknown value is rejected with 422.

# PATCH /api/v1/menu/modifiers/{code} — brand scope only
curl -X PATCH \
  -H "X-Bipbip-Api-Key: $API_KEY" \
  -H "X-Bipbip-Schema-Version: 1.0" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
       "set": {
         "name": "Extras",
         "min": 0,
         "max": 3,
         "type": "checkbox"
       },
       "scope": "brand"
     }' \
  https://merchant-api.bipbip.hn/api/v1/menu/modifiers/GRP-EXTRAS

await fetch(`${BASE}/api/v1/menu/modifiers/${code}`, {
  method: 'PATCH',
  headers: {
    'X-Bipbip-Api-Key': process.env.BIPBIP_API_KEY,
    'X-Bipbip-Schema-Version': '1.0',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "set": {
      "name": "Extras",
      "min": 0,
      "max": 3,
      "type": "checkbox"
    },
    "scope": "brand"
  }),
});

Response

{
  "message": "Operación completada exitosamente",
  "data": {
    "changeId": "chg_9fA2kQ7pLm3XbT10"
  }
}

{
  "type": "https://bipbip.app/probs/invalid-api-key",
  "title": "Unauthorized",
  "detail": "API Key missing or invalid.",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/not-found",
  "title": "Order not found",
  "detail": "Order ord_xxx does not exist or does not belong to the authenticated client.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/validation",
  "title": "Validation failed",
  "detail": "One or more request fields are invalid.",
  "status": 422,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": {
    "errors": {
      "items[0].targetCode": [
        "The targetCode field is required."
      ]
    }
  }
}

POST/api/v1/menu/changes

Heterogeneous change set

Sends changes across different entities in a single operation. Each change targets one entity and carries only the fields to modify.

It is the common funnel

The shortcuts (/availability, /prices) and the per-entity PATCH calls compile internally to this same shape. If your POS accumulates changes and flushes them in batches, this is the endpoint you want.

The whole set must resolve to stores of a single brand

Target stores come from the top level (stores) or from the change itself. Mixing brands in one set is an error.

Body

stores[]array<string>

Target stores that apply to every change in the set.

changes[]arrayrequired

List of declarative changes to apply.

targetEntityenumrequired

product, modifierOption, category, modifierGroup or localProduct.

targetCodestringrequired

Target entity code.

scopeenum

store or brand.

categoryCodestring

Parent category or group code for disambiguation. For modifierOption it is the parent group, required in brand scope.

setobjectrequired

Same fields as the set of the PATCH endpoints. Only present fields are applied.

Returns — 202 Accepted

data.changeIdstring

A single identifier for the whole batch.

# POST /api/v1/menu/changes
curl -X POST \
  -H "X-Bipbip-Api-Key: $API_KEY" \
  -H "X-Bipbip-Schema-Version: 1.0" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
       "stores": [
         "POS_TGU_001",
         "POS_SPS_004"
       ],
       "changes": [
         {
           "targetEntity": "product",
           "targetCode": "BURG-DOBLE",
           "scope": "store",
           "set": {
             "available": false
           }
         },
         {
           "targetEntity": "modifierOption",
           "targetCode": "OPT-QUESO-EXTRA",
           "categoryCode": "GRP-EXTRAS",
           "scope": "store",
           "set": {
             "price": 25
           }
         },
         {
           "targetEntity": "category",
           "targetCode": "CAT-HAMBURGUESAS",
           "scope": "brand",
           "set": {
             "position": 1
           }
         }
       ]
     }' \
  https://merchant-api.bipbip.hn/api/v1/menu/changes

await fetch(`${BASE}/api/v1/menu/changes`, {
  method: 'POST',
  headers: {
    'X-Bipbip-Api-Key': process.env.BIPBIP_API_KEY,
    'X-Bipbip-Schema-Version': '1.0',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "stores": [
      "POS_TGU_001",
      "POS_SPS_004"
    ],
    "changes": [
      {
        "targetEntity": "product",
        "targetCode": "BURG-DOBLE",
        "scope": "store",
        "set": {
          "available": false
        }
      },
      {
        "targetEntity": "modifierOption",
        "targetCode": "OPT-QUESO-EXTRA",
        "categoryCode": "GRP-EXTRAS",
        "scope": "store",
        "set": {
          "price": 25
        }
      },
      {
        "targetEntity": "category",
        "targetCode": "CAT-HAMBURGUESAS",
        "scope": "brand",
        "set": {
          "position": 1
        }
      }
    ]
  }),
});

Response

{
  "message": "Operación completada exitosamente",
  "data": {
    "changeId": "chg_9fA2kQ7pLm3XbT10"
  }
}

{
  "type": "https://bipbip.app/probs/missing-schema-version",
  "title": "Missing schema version",
  "detail": "The X-Bipbip-Schema-Version header is required on mutations.",
  "status": 400,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/invalid-api-key",
  "title": "Unauthorized",
  "detail": "API Key missing or invalid.",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/not-found",
  "title": "Order not found",
  "detail": "Order ord_xxx does not exist or does not belong to the authenticated client.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/validation",
  "title": "Validation failed",
  "detail": "One or more request fields are invalid.",
  "status": 422,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": {
    "errors": {
      "items[0].targetCode": [
        "The targetCode field is required."
      ]
    }
  }
}

POST/api/v1/menu/stores/{storeRemoteId}/products

Create a local product

Registers a product that belongs to a single store, outside the brand's master catalog.

It is always created active — available is not applied

To leave it unavailable, create the product and then adjust availability withPUT /menu/availability.

Without a valid categoryCode, the product is invisible

The customer-facing menu is built by grouping on category. categoryCode is required and must be the code of a category that exists in the store menu — list them withGET /menu/stores/{storeRemoteId}. A product without a valid category is created, but shows up nowhere.

Path parameters

storeRemoteIdstringrequired

Store code defined by you.

Body

codestringrequired

Your product code. BipBip derives its own internal code and keeps yours as remoteCode: you keep addressing the product with your code in later calls. Unique within the store.

namestringrequired

Local product name.

pricenumberrequired

Greater than or equal to 0.

categoryCodestringrequired

A category that exists in the store menu.

descriptionstringoptional

Product description.

channels[]array<string>optional

delivery and/or pickup. If omitted, it is enabled on delivery only.

taxnumberoptional

Allowed values: 0, 0.15 or 0.18. Omitted = 0.

maxPerOrderintegeroptional

Greater than 0. Omitted = 25.

imagestringoptional

Absolute http(s) URL. Re-hosted as WebP in BipBip's bucket.

availablebooleanoptional

Not applied on creation.

Position is not accepted

BackOffice places the product at the end of its category.

# POST /api/v1/menu/stores/{storeRemoteId}/products
curl -X POST \
  -H "X-Bipbip-Api-Key: $API_KEY" \
  -H "X-Bipbip-Schema-Version: 1.0" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
       "code": "LOCAL-EMPANADA",
       "name": "House empanada",
       "price": 45,
       "categoryCode": "CAT-ENTRADAS",
       "description": "Available at this location only",
       "channels": [
         "delivery",
         "pickup"
       ],
       "tax": 0.15,
       "maxPerOrder": 10,
       "image": "https://cdn.your-merchant.com/empanada.jpg"
     }' \
  https://merchant-api.bipbip.hn/api/v1/menu/stores/POS_TGU_001/products

await fetch(`${BASE}/api/v1/menu/stores/${storeRemoteId}/products`, {
  method: 'POST',
  headers: {
    'X-Bipbip-Api-Key': process.env.BIPBIP_API_KEY,
    'X-Bipbip-Schema-Version': '1.0',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "code": "LOCAL-EMPANADA",
    "name": "House empanada",
    "price": 45,
    "categoryCode": "CAT-ENTRADAS",
    "description": "Available at this location only",
    "channels": [
      "delivery",
      "pickup"
    ],
    "tax": 0.15,
    "maxPerOrder": 10,
    "image": "https://cdn.your-merchant.com/empanada.jpg"
  }),
});

Body

// Reads back as origin: "store". Without categoryCode it is created but never shown.
{
  "code": "LOCAL-EMPANADA",
  "name": "Empanada de la casa",
  "price": 45,
  "categoryCode": "CAT-ENTRADAS",
  "description": "Receta propia de esta sucursal"
}

// code is yours: BipBip derives its own and keeps yours. Position is not sent.
{
  "code": "LOCAL-EMPANADA",
  "name": "Empanada de la casa",
  "price": 45,
  "categoryCode": "CAT-ENTRADAS",
  "description": "Receta propia de esta sucursal",
  "channels": [
    "delivery",
    "pickup"
  ],
  "tax": 0.15,
  "maxPerOrder": 10,
  "image": "https://cdn.mi-comercio.com/empanada.jpg"
}

Response

{
  "message": "Operación completada exitosamente",
  "data": {
    "changeId": "chg_9fA2kQ7pLm3XbT10"
  }
}

{
  "type": "https://bipbip.app/probs/missing-schema-version",
  "title": "Missing schema version",
  "detail": "The X-Bipbip-Schema-Version header is required on mutations.",
  "status": 400,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/invalid-api-key",
  "title": "Unauthorized",
  "detail": "API Key missing or invalid.",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/not-found",
  "title": "Order not found",
  "detail": "Order ord_xxx does not exist or does not belong to the authenticated client.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/validation",
  "title": "Validation failed",
  "detail": "One or more request fields are invalid.",
  "status": 422,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": {
    "errors": {
      "items[0].targetCode": [
        "The targetCode field is required."
      ]
    }
  }
}

POST/api/v1/menu/preview

Preview the full menu (dry-run)

Computes the diff of applying a full menu against the current master catalog: what would be created, updated or deactivated. Applies no changes and emits no events.

Run this before PUT /menu

It is read-only and takes exactly the same body. It is how you see the deactivation your submission would cause before causing it.

Semantic validations come back as warnings, not as 422

The 422 covers payload shape. Everything else — "does this code already exist?" and similar — travels inwarnings inside BackOffice's response. Read them: a preview returning200 does not mean everything is fine.

Body — nested tree

categories[]arrayrequired

Menu categories, each with its products nested, and each product with its modifier groups inside. At least one category.

categories[].products[]arrayrequired

Products of the category. At least one.

remoteCodestringrequired

Your stable code. Unique across the whole submitted menu.

name · descriptionstring

Name (required) and description (optional).

pricenumberrequired

Greater than or equal to 0.

tax · maxPerOrdernumber · integeroptional

Tax as a fraction between 0 and 1; maximum units per order greater than 0.

imagestringrequired

Absolute http(s) URL. Required here: a product without an image is rejected with 422.

modifierGroups[]array

Nested groups, with remoteCode, name, min, max, type and their options[].

remoteCode rules

Required on every entity. Safe format: letters, digits and _ . - :, no spaces, up to 100 characters.
Unique across categories; unique across the whole menu for products; unique within a product for groups; unique within a group for options.
Two products declaring a group with the same remoteCode share that group — it is defined once at brand level. Different codes produce separate groups.
BipBip derives its own opaque code from yours. You never send BipBip's code.

# POST /api/v1/menu/preview — dry-run, applies nothing
curl -X POST \
  -H "X-Bipbip-Api-Key: $API_KEY" \
  -H "X-Bipbip-Schema-Version: 1.0" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
       "categories": [
         {
           "remoteCode": "CAT-HAMBURGUESAS",
           "name": "Burgers",
           "position": 1,
           "products": [
             {
               "remoteCode": "BURG-DOBLE",
               "name": "Double BBQ Burger",
               "description": "Double patty, bacon and house BBQ sauce",
               "price": 185,
               "tax": 0.15,
               "maxPerOrder": 10,
               "image": "https://cdn.your-merchant.com/burg-doble.jpg",
               "modifierGroups": [
                 {
                   "remoteCode": "GRP-EXTRAS",
                   "name": "Extras",
                   "min": 0,
                   "max": 3,
                   "type": "checkbox",
                   "options": [
                     {
                       "remoteCode": "OPT-QUESO-EXTRA",
                       "name": "Extra cheese",
                       "price": 22,
                       "isDefault": false,
                       "maxPerOrder": 2
                     }
                   ]
                 }
               ]
             }
           ]
         }
       ]
     }' \
  https://merchant-api.bipbip.hn/api/v1/menu/preview

await fetch(`${BASE}/api/v1/menu/preview`, {
  method: 'POST',
  headers: {
    'X-Bipbip-Api-Key': process.env.BIPBIP_API_KEY,
    'X-Bipbip-Schema-Version': '1.0',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "categories": [
      {
        "remoteCode": "CAT-HAMBURGUESAS",
        "name": "Burgers",
        "position": 1,
        "products": [
          {
            "remoteCode": "BURG-DOBLE",
            "name": "Double BBQ Burger",
            "description": "Double patty, bacon and house BBQ sauce",
            "price": 185,
            "tax": 0.15,
            "maxPerOrder": 10,
            "image": "https://cdn.your-merchant.com/burg-doble.jpg",
            "modifierGroups": [
              {
                "remoteCode": "GRP-EXTRAS",
                "name": "Extras",
                "min": 0,
                "max": 3,
                "type": "checkbox",
                "options": [
                  {
                    "remoteCode": "OPT-QUESO-EXTRA",
                    "name": "Extra cheese",
                    "price": 22,
                    "isDefault": false,
                    "maxPerOrder": 2
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }),
});

Response

{
  "message": "Operación completada exitosamente",
  "data": { /* diff computed by BackOffice + warnings[] */ }
}

{
  "type": "https://bipbip.app/probs/invalid-api-key",
  "title": "Unauthorized",
  "detail": "API Key missing or invalid.",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/validation",
  "title": "Validation failed",
  "detail": "One or more request fields are invalid.",
  "status": 422,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": {
    "errors": {
      "items[0].targetCode": [
        "The targetCode field is required."
      ]
    }
  }
}

{
  "type": "https://bipbip.app/probs/not-found",
  "title": "Order not found",
  "detail": "Order ord_xxx does not exist or does not belong to the authenticated client.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

PUT/api/v1/menu

Apply the full menu

Publishes the brand's master catalog: creates what does not exist, updates what does, and deactivates the items omitted from the submission. Synchronous operation.

Whatever you omit gets deactivated

The menu you send becomes the complete source of truth for the brand. Every master catalog item missing from the submission is deactivated. This is not a partial merge: it is a replacement.

Guardrail against incomplete submissions

If the resulting deactivation exceeds a threshold of the active catalog, BackOffice rejects with409 Conflict and reports the affected counts indetail. To confirm deliberately, resend with?confirmLargeDeactivation=true. If the 409 surprises you, it almost always means your submission is incomplete — not that the threshold is wrong.

It is synchronous: no changeId, no polling

Unlike the rest of the menu write surface, this operation does not return 202. The 200 already reflects the result applied by BackOffice.

Query parameters

confirmLargeDeactivationbooleanoptional

true explicitly confirms a bulk deactivation that the guardrail would block.

Body

categories[]arrayrequired

Same body as POST /menu/preview: nested tree of categories → products → groups → options, identified by your remoteCode.

# PUT /api/v1/menu — applies the full menu (synchronous)
curl -X PUT \
  -H "X-Bipbip-Api-Key: $API_KEY" \
  -H "X-Bipbip-Schema-Version: 1.0" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
       "categories": [
         {
           "remoteCode": "CAT-HAMBURGUESAS",
           "name": "Burgers",
           "position": 1,
           "products": [
             {
               "remoteCode": "BURG-DOBLE",
               "name": "Double BBQ Burger",
               "description": "Double patty, bacon and house BBQ sauce",
               "price": 185,
               "tax": 0.15,
               "maxPerOrder": 10,
               "image": "https://cdn.your-merchant.com/burg-doble.jpg",
               "modifierGroups": [
                 {
                   "remoteCode": "GRP-EXTRAS",
                   "name": "Extras",
                   "min": 0,
                   "max": 3,
                   "type": "checkbox",
                   "options": [
                     {
                       "remoteCode": "OPT-QUESO-EXTRA",
                       "name": "Extra cheese",
                       "price": 22,
                       "isDefault": false,
                       "maxPerOrder": 2
                     }
                   ]
                 }
               ]
             }
           ]
         }
       ]
     }' \
  "https://merchant-api.bipbip.hn/api/v1/menu?confirmLargeDeactivation=false"

await fetch(`${BASE}/api/v1/menu`, {
  method: 'PUT',
  headers: {
    'X-Bipbip-Api-Key': process.env.BIPBIP_API_KEY,
    'X-Bipbip-Schema-Version': '1.0',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "categories": [
      {
        "remoteCode": "CAT-HAMBURGUESAS",
        "name": "Burgers",
        "position": 1,
        "products": [
          {
            "remoteCode": "BURG-DOBLE",
            "name": "Double BBQ Burger",
            "description": "Double patty, bacon and house BBQ sauce",
            "price": 185,
            "tax": 0.15,
            "maxPerOrder": 10,
            "image": "https://cdn.your-merchant.com/burg-doble.jpg",
            "modifierGroups": [
              {
                "remoteCode": "GRP-EXTRAS",
                "name": "Extras",
                "min": 0,
                "max": 3,
                "type": "checkbox",
                "options": [
                  {
                    "remoteCode": "OPT-QUESO-EXTRA",
                    "name": "Extra cheese",
                    "price": 22,
                    "isDefault": false,
                    "maxPerOrder": 2
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }),
});

Response

{
  "message": "Operación completada exitosamente",
  "data": { /* diff computed by BackOffice + warnings[] */ }
}

{
  "type": "https://bipbip.app/probs/invalid-api-key",
  "title": "Unauthorized",
  "detail": "API Key missing or invalid.",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/large-deactivation",
  "title": "Large deactivation blocked",
  "detail": "This submission would deactivate 74 of 92 active items. Resend with ?confirmLargeDeactivation=true to confirm.",
  "status": 409,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/validation",
  "title": "Validation failed",
  "detail": "One or more request fields are invalid.",
  "status": 422,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": {
    "errors": {
      "items[0].targetCode": [
        "The targetCode field is required."
      ]
    }
  }
}

{
  "type": "https://bipbip.app/probs/not-found",
  "title": "Order not found",
  "detail": "Order ord_xxx does not exist or does not belong to the authenticated client.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

GET/api/v1/menu/stores/{storeRemoteId}

Get a store's menu

Returns the store's full current catalog. A restricted item still appears in the response instead of disappearing. Not cached: the menu is live state.

Two fields save you from interpreting rules

orderable: whether the item can be ordered right now. Already computed — do not derive it yourself.
resumesAt: when it becomes available again on its own. null means it does not come back on its own and a merchant action is required.

Path parameters

storeRemoteIdstringrequired

Store code defined by you.

Returns — 200 OK

data.categories[]array

Categories sorted by position, with their products nested.

code · name · positionstring · string · integer

Code assigned by BipBip, visible name and sort order within the menu.

data.categories[].products[]array

Value fields (price, name, description, channels) reflect what is in effect today.

code · remoteCodestring

BipBip's code (the one write endpoints accept) and your own POS code.

originenum

brand (master catalog) or store (local product).

orderableboolean

Whether the product can be ordered right now.

resumesAtISO 8601 | null

When it comes back on its own. null = action required.

channels[]array<string>

Channels in effect. Empty = blocked on all of them.

imagestring | null

URL already re-hosted by BipBip (WebP). Not the URL you sent.

modifierGroups[]array

Groups with min, max, type and their options[], which repeat the same override contract.

overrides[]array

Store overrides on top of the master catalog, sorted by precedence: overrides[0] is the one that drives orderable and resumesAt. Items with nothing on top omit this field.

typeenum

substituted, unavailable, scheduled, channel or value. It discriminates the shape: only the fields that apply to that type are populated.

reasonstring | null

Reason declared by whoever set it, when there is one.

replacedBystring | null

Code of the item replacing it. Only on substituted.

windowobject | null

days[], startTime, endTime. Only on scheduled, and informational — to decide, use resumesAt.

fields[]array

On channel and value: field, value (in effect) and base (the master value it reverts to if the override is removed).

# GET /api/v1/menu/stores/{storeRemoteId}
curl \
  -H "X-Bipbip-Api-Key: $API_KEY" \
  https://merchant-api.bipbip.hn/api/v1/menu/stores/POS_TGU_001

const res = await fetch(`${BASE}/api/v1/menu/stores/${storeRemoteId}`, {
  method: 'GET',
  headers: { 'X-Bipbip-Api-Key': process.env.BIPBIP_API_KEY },
});
const { data } = await res.json();
// overrides[0] is the one that drives orderable and resumesAt

Response

{
  "message": "Operación completada exitosamente",
  "data": {
    "categories": [
      {
        "code": "CAT-HAMBURGUESAS",
        "name": "Hamburguesas",
        "position": 1,
        "products": [
          {
            "code": "BURG-DOBLE",
            "categoryCode": "CAT-HAMBURGUESAS",
            "name": "Hamburguesa Doble BBQ",
            "price": 185,
            "tax": 0.15,
            "position": 1,
            "maxPerOrder": 25,
            "origin": "brand",
            "orderable": false,
            "channels": [
              "delivery"
            ],
            "remoteCode": "POS-1123",
            "description": "Doble carne, tocino y salsa BBQ de la casa",
            "image": "https://cdn.bipbip.hn/products/burg-doble.webp",
            "resumesAt": "2026-08-10T18:00:00-06:00",
            "overrides": [
              {
                "type": "scheduled",
                "window": {
                  "days": [
                    "mon",
                    "tue"
                  ],
                  "startTime": "18:00",
                  "endTime": "23:00"
                }
              },
              {
                "type": "value",
                "fields": [
                  {
                    "field": "price",
                    "value": 185,
                    "base": 160
                  }
                ]
              }
            ],
            "modifierGroups": [
              {
                "code": "GRP-EXTRAS",
                "name": "Extras",
                "min": 0,
                "max": 3,
                "type": "checkbox",
                "position": 1,
                "options": [
                  {
                    "code": "OPT-QUESO-EXTRA",
                    "name": "Queso extra",
                    "price": 22,
                    "isDefault": false,
                    "orderable": false,
                    "remoteCode": "POS-OPT1",
                    "maxPerOrder": 2,
                    "overrides": [
                      {
                        "type": "unavailable"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "code": "PAPAS-MED",
            "categoryCode": "CAT-HAMBURGUESAS",
            "name": "Papas medianas",
            "price": 55,
            "tax": 0.15,
            "position": 2,
            "maxPerOrder": 25,
            "origin": "brand",
            "orderable": true,
            "channels": [
              "delivery",
              "pickup"
            ],
            "remoteCode": "POS-2201"
          }
        ]
      }
    ]
  }
}

{
  "type": "https://bipbip.app/probs/invalid-api-key",
  "title": "Unauthorized",
  "detail": "API Key missing or invalid.",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/not-found",
  "title": "Order not found",
  "detail": "Order ord_xxx does not exist or does not belong to the authenticated client.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/rate-limit-exceeded",
  "title": "Too many requests",
  "detail": "Request quota exceeded for this API Key.",
  "status": 429,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

GET/api/v1/menu/changes/{changeId}

Get a change's status

Returns the status and per-store results of a menu change request.

The global status is not the result

status: "Applied" means BackOffice finished processing — not that every store ended up correct. The real outcome is per store: walkresults[] and check applied on each row.

Path parameters

changeIdstringrequired

Identifier returned in the 202 of the write (chg_ + 16 characters).

Returns — 200 OK

data.changeIdstring

The same identifier the 202 returned.

data.statusenum

Pending while BackOffice applies, Applied once it finished.

data.schemaVersionstring

Schema version the change was submitted with.

data.submittedAtISO 8601

When BipBip accepted the request.

data.completedAtISO 8601 | null

When it finished applying across all stores. null while still pending.

data.results[]array

One row per (store, entity) affected. Best-effort per store.

storeRemoteId · storeIdstring | null · integer | null

Store code and id. null on brand scope results: there is no concrete store to report.

targetEntity · targetCodestring

Affected entity and its code, exactly as you sent it.

appliedboolean

Whether the change was applied at this store. false does not invalidate the other rows.

errorCodestring | null

Stable failure code — for example UNKNOWN_CATEGORY. Safe for retry logic.

errorMessagestring | null

Human-readable failure description. For diagnostics: do not parse it.

appliedAtISO 8601 | null

When it was applied at this store. null if it failed.

# GET /api/v1/menu/changes/{changeId}
curl \
  -H "X-Bipbip-Api-Key: $API_KEY" \
  https://merchant-api.bipbip.hn/api/v1/menu/changes/chg_9fA2kQ7pLm3XbT10

const res = await fetch(`${BASE}/api/v1/menu/changes/${changeId}`, {
  method: 'GET',
  headers: { 'X-Bipbip-Api-Key': process.env.BIPBIP_API_KEY },
});
const { data } = await res.json();
// check applied on every row of data.results, not just data.status

Response

{
  "message": "Operación completada exitosamente",
  "data": {
    "changeId": "chg_9fA2kQ7pLm3XbT10",
    "status": "Applied",
    "schemaVersion": "1.0",
    "submittedAt": "2026-08-07T17:12:44Z",
    "completedAt": "2026-08-07T17:12:51Z",
    "results": [
      {
        "storeRemoteId": "POS_TGU_001",
        "storeId": 1,
        "targetEntity": "product",
        "targetCode": "BURG-DOBLE",
        "applied": true,
        "appliedAt": "2026-08-07T17:12:51Z"
      },
      {
        "storeRemoteId": "POS_SPS_004",
        "storeId": 4,
        "targetEntity": "product",
        "targetCode": "BURG-DOBLE",
        "applied": false,
        "errorCode": "UNKNOWN_CATEGORY",
        "errorMessage": "La categoría 'CAT-XYZ' no existe en el menú de la marca."
      }
    ]
  }
}

{
  "type": "https://bipbip.app/probs/invalid-api-key",
  "title": "Unauthorized",
  "detail": "API Key missing or invalid.",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/not-found",
  "title": "Order not found",
  "detail": "Order ord_xxx does not exist or does not belong to the authenticated client.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/rate-limit-exceeded",
  "title": "Too many requests",
  "detail": "Request quota exceeded for this API Key.",
  "status": 429,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

GET/api/v1/menu/capabilities

Capability matrix

For every combination of entity, field and scope, states whether the change is editable in the current version. Only shipped combinations are listed.

It is the source of truth for what is editable today

Deferred combinations do not appear in the matrix, and the validator rejects them with422. Query it before building integrations on new fields, instead of discovering the limit in production.

Returns — 200 OK

data.capabilities[]array

Combinations the API accepts today.

entityenum

product, modifierOption, category or modifierGroup.

fieldstring

Editable field — for example price, available, schedule or channels.

scopeenum

store (per-store override, reversible) or brand (master catalog, affects every store).

pendingCustomerRolloutboolean

true when the change is accepted and persisted but the customer app does not reflect it yet. Known gap: the write does not fail, but the effect is not visible to the end consumer.

data.notesstring | null

Clarifications on the current version's limitations.

Current restrictions worth keeping in mind

available is deferred in brand scope for product and modifierOption: it is a per-store override concept.
category and modifierGroup are brand-only: they have no per-store override.
brand scope applies to Domicilio only (delivery/pickup).
price and name of modifierOption in store scope carry pendingCustomerRollout: true.

# GET /api/v1/menu/capabilities
curl \
  -H "X-Bipbip-Api-Key: $API_KEY" \
  https://merchant-api.bipbip.hn/api/v1/menu/capabilities

const res = await fetch(`${BASE}/api/v1/menu/capabilities`, {
  method: 'GET',
  headers: { 'X-Bipbip-Api-Key': process.env.BIPBIP_API_KEY },
});
const { data } = await res.json();
// a combo missing from data.capabilities is rejected with 422

Response

{
  "message": "Operación completada exitosamente",
  "data": {
    "capabilities": [
      { "entity": "product", "field": "available", "scope": "store", "pendingCustomerRollout": false },
      { "entity": "product", "field": "schedule", "scope": "store", "pendingCustomerRollout": false },
      { "entity": "modifierOption", "field": "price", "scope": "store", "pendingCustomerRollout": true },
      { "entity": "product", "field": "image", "scope": "brand", "pendingCustomerRollout": false },
      { "entity": "category", "field": "position", "scope": "brand", "pendingCustomerRollout": false }
      // … the endpoint returns the full matrix
    ],
    "notes": "…"
  }
}

{
  "type": "https://bipbip.app/probs/invalid-api-key",
  "title": "Unauthorized",
  "detail": "API Key missing or invalid.",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

{
  "type": "https://bipbip.app/probs/rate-limit-exceeded",
  "title": "Too many requests",
  "detail": "Request quota exceeded for this API Key.",
  "status": 429,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

REST API Reference

Authentication

Idempotency-Key

Rate limits

Errors

Generic error

Invalid transition (409)

Validation error (422)

Orders

Accept an order

Path parameters

Headers

Body

Returns — 202 Accepted

Reject an order

Path parameters

Headers

Body

Returns — 202 Accepted

Advance status

Path parameters

Headers

Body

Returns — 202 Accepted

Get an order

Path parameters

Headers

Returns — 200 OK

Driver release — how it looks in history

List orders

Headers

Query parameters

Returns — 200 OK

Menu

The two scopes

Change availability

Headers

Body

Returns — 202 Accepted

Change prices

Body

Returns — 202 Accepted

Modify a product

Path parameters

Body

Modify a modifier option

Path parameters

Body

Modify a category

Path parameters

Body

Modify a modifier group

Path parameters

Body

Heterogeneous change set

Body

Returns — 202 Accepted

Create a local product

Path parameters

Body

Preview the full menu (dry-run)

Body — nested tree

Apply the full menu

Query parameters

Body

Get a store's menu

Path parameters

Returns — 200 OK

Get a change's status

Path parameters

Returns — 200 OK

Capability matrix

Returns — 200 OK

Driver release — how it looks in `history`