openapi: 3.1.1 info: title: Beckn Protocol API description: | The Beckn Protocol API v2.0.0 — an OpenAPI 3.1.1 specification defining one named path per Beckn protocol action. ## Scope Designed for interoperability across any value-exchange use case across any industry sector including but not necessarily limited to retail, mobility, logistics, energy, healthcare, skilling, financial services, carbon trading, hiring, and data exchange. ## Value-exchange Flows (Normative) - **Discovery**: Catalog publishing, Catalog discovery and browsing - **Contracting (previously called Ordering)**: Price negotiation, Terms negotiation, Contract agreement - **Performance (previously called Fulfillment)** : Status updates, real-time tracking, contract cancellation / termination, contract amendment - **Post-performance (previously called Post-fulfillment)**: Rating, feedback, and support ## Fabric Actors (Normative) Any actor on the fabric participating in a value-exchange transaction MUST be one of the following: 1. **Consumer:** A verified entity on the fabric that seeks to obtain an item of value (Resource) from a provider who owns that resource. 2. **Provider:** A verified entity on the fabric that provides the item of value (Resource) to the consumer who wants that resource. 3. **Consumer Node (CN)** — A verified, on-fabric application that onboards consumers or consumer-facing agents as clients by creating or verifying their identity on the fabric. It initiates value-exchange transactions on behalf of its clients. It MUST provide an addressable endpoint to routing incoming messages to the respective consumers it onboards. It SHOULD implement a client-facing interface for discovery, contracting, fulfillment and post-fulfillment workflows. 4. **Provider Node (PN)** — A verified, on-fabric application that onboards providers or provider-facing agents as clients by creating or verifying their identity on the fabric. Its network-facing API MUST implement the Beckn Protocol endpoints that receive value-exchange requests from calling CNs and respond to them via asynchronous callback endpoints implemented by the CNs. It MUST provide an addressable endpoint to routing incoming messages to the respective providers it has onboarded. It SHOULD provide a client-facing interface for publishing and managing catalogs, contracts, fulfillments, ratings, feedback, and providing support to CNs. 5. **Discovery Service (DS)**: — A verified on-fabric application that enables discovery of catalogs only accessible via CNs. Its network-facing API MUST implement the Beckn Protocol API endpoints that receive catalog discovery requests from CNs and asynchronously respond with catalogs from various providers. It MUST ensure the catalog it has is the most recent, either by subscribing to updates from the fabric cataloging service (see next section — deprecated, see NFH-014) or by crawling and independently verifying PN-hosted catalog files per NFH-014's decentralized publishing model. It MAY be implemented as an independent SaaS for CNs to consume, or implemented by the CNs themselves. 6. **Network Facilitator Organization (NFO)** — Entity that manages a subnet on the fabric consisting of CNs, PNs, and DSes. The above actors can exist as separate applications with distinct fabric identities, or can be bundled inside a single application. Each role MUST have a separate identity and public key on the fabric, even if they are all implemented of a single platform. **Note on legacy terminology:** *Consumer Node (CN)* and *Provider Node (PN)* were previously referred to as *Beckn Application Platform (BAP)* and *Beckn Provider Platform (BPP)* respectively. The acronyms have been updated throughout this specification, but the corresponding wire-level field names — `bapId`, `bapUri`, `bppId`, `bppUri` — are **retained unchanged** in `context` to preserve backward compatibility with existing integrations. Read `bapId` / `bapUri` as the CN's identity and address, and `bppId` / `bppUri` as the PN's. ## Required Infrastructure Building Blocks (Threads) To perform trusted value-exchange, NPs MUST consume the following services provided on the Fabric. These services are a species of one, and MUST NOT be implemented on any subnet inside the fabric, only consumed. 1. **NS** (Namespacing Service) — Identity service provided to all NPs to create their unique and verified identity and establish their presence on the fabric. Powered by dedi.global, an implementation of dedi protocol. 2. **GRR** (Global Root Registry) — Global identity and address lookup service used by all NPs. 3. **CS** (Cataloging Service) — Common service provided to all NPs for programmable catalog discoverability. Deprecated: superseded by the decentralized catalog publishing and discovery model in NFH-014; remains available for existing implementations. **Note:** Both the Namespacing Service and Global Root Registry service MUST be consumed using dedi protocol API. The API for consuming the Namespacing and Global Root Registry services are out of scope of this API specification and can be found in the dedi protocol documentation. ## Prerequisites for Production 1. **Namespace creation** — Every actor (Consumer, Provider, NFO, CN, PN, DS) MUST claim a unique namespace on the fabric created via the namespacing service. For consumers and providers, the namespace can be created by themselves, or by the CNs and PNs that have respectively onboarded them. 2. **Network address registration** — CNs and PNs that are onboarding their respective users (consumers and providers) MUST ensure that their addresses are properly registered on their respective users' namespaces. 3. **Subnet registration** — Actors participating in a fabric subnet MUST register their network identifier and relevant addresses on the registry managed by that subnet's NFO in its own namespace. ## Common Implementation Requirements The following apply to every request in this specification unless an endpoint states otherwise: 1. **Payload Structure** — Every request and callback body MUST conform to the Beckn envelope: ```json { "context": { ... }, "message": { ... } } ``` 2. **Context** — The `context` object MUST include at minimum: ``` - `action`, - `version` (always set to 2.0.0) - `transactionId` - `messageId` - `bapId` or `bppId` ``` 3. **`context.try`** — The `context.try` property when set to `true`, allows a requesting NP to preview the consequences of an action before committing to that action. - This field is applicable to `update / on_update` and `cancel / on_cancel` endpoints ONLY. - NPs MUST NOT send this flag, or if sent, completely ignore the value of this flag in other endpoints. - When the caller wants to commit the request, it MUST set the `context.try` to `false`, with the `context.requestDigest` containing the digest of the previous payload that it received as a response to the request with `try` set to true. If this value is not sent, the receiver NP MUST return a NACK with an appropriate error. - This is to ensure that NPs are not directly committing requests that without knowing the consequences of that operation. 4. **Message** — The `message` object carries the action-specific payload defined by the path's request schema. 5. **Beckn HTTP Signature** — Every request MUST carry a valid Beckn HTTP Signature in the `Authorization` header. ## Standard Response Families All action endpoints share five standard response outcomes. Endpoint descriptions reference these by name. | Code | Name | Semantics | |------|------|-----------| | 200 | **Ack** | The implementer authenticated the request and accepted it for processing. For async actions, the business result arrives via callback. | | 202 | **AckNoCallback** | The implementer received and authenticated the request but will not produce a callback (e.g., no matching results found). | | 400 | **NackBadRequest** | The request body is structurally invalid or fails semantic validation. The implementer MUST NOT process the request further; the caller MUST correct the request before retrying. | | 401 | **NackUnauthorized** | The Beckn HTTP Signature is absent, expired, or fails Registry key verification. The implementer MUST NOT process the request; the caller MUST obtain a valid signature before retrying. | | 500 | **ServerError** | An unexpected internal failure occurred. The caller SHOULD treat this as transient and MAY retry after a backoff interval. | version: 2.0.0 contact: name: Beckn Protocol url: https://beckn.io license: name: CC-BY-NC-SA 4.0 International url: https://creativecommons.org/licenses/by-nc-sa/4.0/deed.en tags: - name: Discovery description: Discover catalogs published by providers - name: Contracting / Ordering description: Negotiate and agree on pricing, terms and establish dual-digitally signed contracts - name: Fulfillment description: Track, update and cancel active contracts - name: Post-Fulfillment description: Rate and support completed contracts - name: Fabric API - Cataloging Service description: >- Publish catalogs to the Cataloging Service (CS) on the Fabric and subscribe to catalog updates. Deprecated: superseded by the decentralized catalog publishing and discovery model in NFH-014. These endpoints remain fully defined and supported for existing implementations; new integrations SHOULD use NFH-014 instead. security: [] servers: - url: https://{subscriberUrl} description: Base URL of the Beckn network participant endpoint. Implementations MUST substitute `{subscriberUrl}` with the subscriber_url returned by the subnet registry lookup for the NP's namespace id and networkId. variables: subscriberUrl: default: example.beckn.io description: Network address of the NP, resolved via the subnet registry lookup using the NP's namespace id and networkId. paths: /discover: post: summary: Discover catalogs on a network description: "The CN sends a discovery request to the DS (Discovery Service),\ \ which searches its indexed catalog store for resources and offers matching\ \ the supplied intent.\n\nFabric context: The DS maintains its catalog index\ \ either by subscribing to the CS (Cataloging Service) on the Fabric (deprecated,\ \ see NFH-014), or by crawling and independently verifying PN-hosted catalog\ \ files per NFH-014's decentralized model. The CN does not interact directly\ \ with the Fabric for discovery.\n\nThe message\ \ MUST contain an Intent object. The Intent carries textSearch, JSONPath filter\ \ expressions per RFC 9535, spatial constraints, and media search inputs that\ \ the DS evaluates against its indexed catalog store.\n\nCallback relationship:\ \ When matching catalogs are found, the DS sends an /on_discover callback to\ \ the CN carrying an OnDiscoverAction with the matching catalogs. The CN\ \ MUST correlate the callback using the messageId from Context.\n\nResponse\ \ codes: Ack, AckNoCallback, NackBadRequest, NackUnauthorized, ServerError." operationId: discover tags: - Discovery parameters: - $ref: '#/components/parameters/AuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: discover message: $ref: '#/components/schemas/DiscoverAction' responses: '200': $ref: '#/components/responses/Ack' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '403': $ref: '#/components/responses/NackDiscretionary' '202': $ref: '#/components/responses/AckNoCallback' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /on_discover: post: summary: Callback — return catalogs to the CN description: "The DS (Discovery Service) calls this endpoint on the CN, delivering\ \ catalogs that match the intent submitted in a prior /discover request.\n\n\ Additional preconditions: A /discover request MUST have been sent by the CN\ \ and accepted (200 Ack) by the DS before this callback is triggered.\n\nThe\ \ message MUST contain an OnDiscoverAction with one or more Catalog objects\ \ matching the original intent.\n\nCallback relationship: Triggered by the\ \ DS after evaluating the /discover request against its indexed catalog store.\ \ The CN MUST use the messageId in Context to correlate this callback with\ \ the originating /discover call.\n\nResponse codes: Ack, NackBadRequest,\ \ NackUnauthorized, ServerError." operationId: onDiscover tags: - Discovery parameters: - $ref: '#/components/parameters/CallbackAuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: on_discover message: $ref: '#/components/schemas/OnDiscoverAction' responses: '200': $ref: '#/components/responses/Ack' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /select: post: summary: CN selects items/resources and requests a quote description: "The CN sends a selection to the PN, identifying specific resources\ \ and offers from a previously discovered catalog and requesting a priced quote.\n\ \nAdditional preconditions: A /discover request MUST have completed and the\ \ CN MUST have received at least one /on_discover callback containing the\ \ catalog from which the selected items are drawn. No personal identifiable\ \ information (PII) is shared at this stage.\n\nThe message MUST contain a\ \ SelectAction with a Contract object specifying the selected commitments, resources,\ \ and offers. The Contract MUST NOT include billing or fulfillment personal\ \ details at this stage.\n\nCallback relationship: After computing the priced\ \ quote, the PN MUST send an /on_select callback to the CN carrying the\ \ updated Contract with offer-linked considerations. The CN MUST correlate\ \ the callback using the messageId from Context.\n\nResponse codes: Ack, AckNoCallback,\ \ NackBadRequest, NackUnauthorized, ServerError." operationId: select tags: - Contracting / Ordering parameters: - $ref: '#/components/parameters/AuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: select message: $ref: '#/components/schemas/SelectAction' responses: '200': $ref: '#/components/responses/Ack' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '403': $ref: '#/components/responses/NackDiscretionary' '202': $ref: '#/components/responses/AckNoCallback' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /on_select: post: summary: PN returns a priced quote description: "The PN calls this endpoint on the CN, delivering a priced quote\ \ computed from the resources and offers submitted in the preceding /select\ \ request.\n\nAdditional preconditions: A /select request MUST have been sent\ \ by the CN and accepted (200 Ack) by the PN before this callback is triggered.\n\ \nThe message MUST contain an OnSelectAction with a Contract object updated\ \ to include offer-level considerations and a total priced quote. The CN uses\ \ this quote to decide whether to proceed to /init.\n\nCallback relationship:\ \ This endpoint is triggered by the PN after evaluating the selection and\ \ computing a priced quote. The CN MUST use the messageId in Context to correlate\ \ this callback with the originating /select call and SHOULD present the returned\ \ quote to the consumer before proceeding.\n\nResponse codes: Ack, NackBadRequest,\ \ NackUnauthorized, ServerError." operationId: onSelect tags: - Contracting / Ordering parameters: - $ref: '#/components/parameters/CallbackAuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: on_select message: $ref: '#/components/schemas/OnSelectAction' responses: '200': $ref: '#/components/responses/Ack' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /init: post: summary: CN initiates final contract — submits billing, fulfillment and payment intent description: "The CN sends billing, fulfillment, and payment intent details\ \ to the PN so that the PN can generate a final draft contract including\ \ personalized payment terms.\n\nAdditional preconditions: A /select request\ \ MUST have completed and the CN MUST have received an /on_select callback\ \ with a priced quote before this endpoint may be called.\n\nThe message MUST\ \ contain an InitAction with a Contract object that includes participant billing\ \ details, performance (fulfillment) preferences, and initial payment intent.\ \ The PN uses this information to finalize payment terms.\n\nCallback relationship:\ \ After generating the final draft contract with payment terms, the PN MUST\ \ send an /on_init callback to the CN. The PN MUST NOT request payment before\ \ the /on_init stage. The CN MUST correlate the callback using the messageId\ \ from Context.\n\nResponse codes: Ack, AckNoCallback, NackBadRequest, NackUnauthorized,\ \ ServerError." operationId: init tags: - Contracting / Ordering parameters: - $ref: '#/components/parameters/AuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: init message: $ref: '#/components/schemas/InitAction' responses: '200': $ref: '#/components/responses/Ack' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '403': $ref: '#/components/responses/NackDiscretionary' '202': $ref: '#/components/responses/AckNoCallback' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /on_init: post: summary: PN returns final draft contract with payment terms description: "The PN calls this endpoint on the CN, delivering the final draft\ \ contract that includes personalized payment terms, billing confirmation,\ \ and any settlement conditions.\n\nAdditional preconditions: A /init request\ \ MUST have been sent by the CN and accepted (200 Ack) by the PN before\ \ this callback is triggered. The PN MUST NOT request or collect payment\ \ before this stage.\n\nThe message MUST contain an OnInitAction with a Contract\ \ object that reflects the finalized draft state including payment terms, billing\ \ confirmation, and settlement placeholders. The CN reviews these terms before\ \ proceeding to /confirm.\n\nCallback relationship: This endpoint is triggered\ \ by the PN after generating the final draft contract in response to /init.\ \ The CN MUST use the messageId in Context to correlate this callback and\ \ SHOULD present the payment terms to the consumer for acceptance before calling\ \ /confirm.\n\nResponse codes: Ack, NackBadRequest, NackUnauthorized, ServerError." operationId: onInit tags: - Contracting / Ordering parameters: - $ref: '#/components/parameters/CallbackAuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: on_init message: $ref: '#/components/schemas/OnInitAction' responses: '200': $ref: '#/components/responses/Ack' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /confirm: post: summary: CN confirms the contract description: "The CN signals unconditional acceptance of all negotiated terms\ \ and provides payment proof or a payment reference to the PN, requesting\ \ that the PN convert the draft contract into a binding commitment.\n\nAdditional\ \ preconditions: An /on_init callback MUST have been received by the CN carrying\ \ the final draft contract with payment terms. The consumer MUST have accepted\ \ those terms before this endpoint may be called.\n\nThe message MUST contain\ \ a ConfirmAction with the full Contract object including payment proof or\ \ reference in the settlements array. The PN uses this evidence to verify\ \ payment and activate the contract.\n\nCallback relationship: After verifying\ \ payment and activating the contract, the PN MUST send an /on_confirm callback\ \ to the CN carrying the confirmed Contract with its assigned ID and initial\ \ fulfillment state. The CN MUST correlate the callback using the messageId\ \ from Context.\n\nResponse codes: Ack, AckNoCallback, NackBadRequest, NackUnauthorized,\ \ ServerError." operationId: confirm tags: - Contracting / Ordering parameters: - $ref: '#/components/parameters/AuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: confirm message: $ref: '#/components/schemas/ConfirmAction' responses: '200': $ref: '#/components/responses/Ack' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '403': $ref: '#/components/responses/NackDiscretionary' '202': $ref: '#/components/responses/AckNoCallback' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /on_confirm: post: summary: PN returns the confirmed contract description: "The PN calls this endpoint on the CN, delivering the confirmed\ \ contract with its PN-assigned identifier and the initial performance state\ \ after verifying payment and activating the commitment.\n\nAdditional preconditions:\ \ A /confirm request MUST have been sent by the CN and accepted (200 Ack)\ \ by the PN. The PN MUST have verified payment proof before triggering this\ \ callback.\n\nThe message MUST contain an OnConfirmAction with the Contract\ \ object whose status is set to ACTIVE, whose id field carries the PN-assigned\ \ contract identifier, and whose performance array reflects the initial fulfillment\ \ state.\n\nCallback relationship: This endpoint is triggered by the PN after\ \ verifying payment and activating the contract in response to /confirm. The\ \ CN MUST use the messageId in Context to correlate this callback and MUST\ \ store the contract id for subsequent status, track, update, cancel, rate,\ \ and support interactions.\n\nResponse codes: Ack, NackBadRequest, NackUnauthorized,\ \ ServerError." operationId: onConfirm tags: - Contracting / Ordering parameters: - $ref: '#/components/parameters/CallbackAuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: on_confirm message: $ref: '#/components/schemas/OnConfirmAction' responses: '200': $ref: '#/components/responses/Ack' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /status: post: summary: CN requests the current state of an contract description: "The CN requests the current state of an active contract from\ \ the PN by providing the contract identifier received in the /on_confirm\ \ callback.\n\nAdditional preconditions: A /confirm request MUST have completed\ \ and the CN MUST have received an /on_confirm callback with a confirmed Contract\ \ carrying a valid id before this endpoint may be called. CNs SHOULD NOT\ \ long-poll using repeated /status calls; the PN MAY push significant state\ \ changes proactively via /on_status.\n\nThe message MUST contain a StatusAction\ \ with a Contract object whose id field identifies the contract being queried.\n\ \nCallback relationship: After retrieving the contract state, the PN MUST\ \ send an /on_status callback carrying the full Contract object with the current\ \ performance and status fields. The PN MAY also send /on_status callbacks\ \ proactively for significant state changes without a prior /status request.\ \ The CN MUST correlate solicited callbacks using the messageId from Context.\n\ \nResponse codes: Ack, AckNoCallback, NackBadRequest, NackUnauthorized, ServerError." operationId: status tags: - Fulfillment parameters: - $ref: '#/components/parameters/AuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: status message: $ref: '#/components/schemas/StatusAction' responses: '200': $ref: '#/components/responses/Ack' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '403': $ref: '#/components/responses/NackDiscretionary' '202': $ref: '#/components/responses/AckNoCallback' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /on_status: post: summary: PN returns the current state of the contract description: "The PN calls this endpoint on the CN, delivering the current\ \ state of an active contract including performance and fulfillment updates.\ \ This endpoint covers significant state changes; it is not intended for real-time\ \ position or progress tracking, for which the CN MUST use /track and /on_track.\n\ \nAdditional preconditions: Either a /status request MUST have been accepted\ \ (200 Ack) by the PN, or the PN is sending a proactive push for a significant\ \ state change on an already-confirmed contract. The PN MAY send proactive\ \ /on_status callbacks without a preceding /status request for significant\ \ contract state transitions.\n\nThe message MUST contain an OnStatusAction\ \ with the full Contract object reflecting the current status and performance\ \ state.\n\nCallback relationship: This endpoint is triggered by the PN either\ \ in response to a /status request or proactively when a significant contract\ \ state change occurs. The CN MUST use the messageId in Context to correlate\ \ solicited callbacks and MUST handle unsolicited callbacks by updating the\ \ locally held contract state.\n\nResponse codes: Ack, NackBadRequest, NackUnauthorized,\ \ ServerError." operationId: onStatus tags: - Fulfillment parameters: - $ref: '#/components/parameters/CallbackAuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: on_status message: $ref: '#/components/schemas/OnStatusAction' responses: '200': $ref: '#/components/responses/Ack' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /track: post: summary: CN requests a real-time tracking handle for an active contract description: "The CN requests a real-time tracking handle from the PN for\ \ an active fulfillment or performance stage of a confirmed contract. This\ \ endpoint provides a URL or WebSocket endpoint for continuous position and\ \ progress updates; it is not intended for contract state change notifications,\ \ for which the CN MUST use /status and /on_status.\n\nAdditional preconditions:\ \ A /confirm request MUST have completed and the CN MUST have received an\ \ /on_confirm callback with a confirmed Contract before this endpoint may be\ \ called.\n\nThe message MUST contain a TrackAction with a Tracking object\ \ whose contract.id identifies the contract whose performance stage is to be\ \ tracked.\n\nCallback relationship: After preparing the tracking handle, the\ \ PN MUST send an /on_track callback to the CN carrying a Tracking object\ \ with the URL or WebSocket endpoint. The CN MUST correlate the callback\ \ using the messageId from Context and MAY open the tracking connection immediately\ \ upon receipt.\n\nResponse codes: Ack, AckNoCallback, NackBadRequest, NackUnauthorized,\ \ ServerError." operationId: track tags: - Fulfillment parameters: - $ref: '#/components/parameters/AuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: track message: $ref: '#/components/schemas/TrackAction' responses: '200': $ref: '#/components/responses/Ack' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '403': $ref: '#/components/responses/NackDiscretionary' '202': $ref: '#/components/responses/AckNoCallback' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /on_track: post: summary: PN returns real-time tracking handle and status description: "The PN calls this endpoint on the CN, delivering a Tracking\ \ handle containing the URL or WebSocket endpoint through which the CN may\ \ subscribe to real-time fulfillment position and progress updates.\n\nAdditional\ \ preconditions: A /track request MUST have been sent by the CN and accepted\ \ (200 Ack) by the PN before this callback is triggered.\n\nThe message MUST\ \ contain an OnTrackAction with a Tracking object that includes a url for the\ \ real-time data stream and a status field indicating whether tracking is ACTIVE\ \ or INACTIVE.\n\nCallback relationship: This endpoint is triggered by the\ \ PN in response to a /track request. The CN MUST use the messageId in Context\ \ to correlate this callback with the originating /track call and SHOULD connect\ \ to the provided tracking URL or WebSocket endpoint to receive real-time updates.\n\ \nResponse codes: Ack, NackBadRequest, NackUnauthorized, ServerError." operationId: onTrack tags: - Fulfillment parameters: - $ref: '#/components/parameters/CallbackAuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: on_track message: $ref: '#/components/schemas/OnTrackAction' responses: '200': $ref: '#/components/responses/Ack' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /update: post: summary: CN requests a mutation to an active contract description: "The CN requests the PN to mutate an active contract, which may\ \ involve changes to committed resources, quantities, billing details, performance\ \ preferences, or payment arrangements.\n\nAdditional preconditions: A /confirm\ \ request MUST have completed and the CN MUST hold a confirmed Contract with\ \ a valid id before this endpoint may be called.\n\nThe message MUST contain\ \ an UpdateAction with the Contract object reflecting the desired mutation.\ \ When context.try is set to true, the CN is requesting a preview of the\ \ updated terms without committing state; the PN MUST respond via /on_update\ \ with recalculated terms but MUST NOT change any persistent state. When context.try\ \ is false (the default), the CN MUST include context.requestDigest containing\ \ the digest of the on_update preview response it received; if context.requestDigest\ \ is absent or does not match, the PN MUST return a NackBadRequest. The PN\ \ MUST apply the change and respond with the confirmed updated contract.\n\nCallback relationship:\ \ After processing the update request, the PN MUST send an /on_update callback\ \ to the CN. When context.try was true, the callback carries updated terms\ \ without state change. When context.try was false, the callback carries the\ \ confirmed updated contract. The PN MAY also send unsolicited /on_update\ \ callbacks for PN-initiated contract mutations. The CN MUST correlate\ \ solicited callbacks using the messageId from Context.\n\nResponse codes:\ \ Ack, AckNoCallback, NackBadRequest, NackUnauthorized, ServerError." operationId: update tags: - Fulfillment parameters: - $ref: '#/components/parameters/AuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: update message: $ref: '#/components/schemas/UpdateAction' responses: '200': $ref: '#/components/responses/Ack' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '403': $ref: '#/components/responses/NackDiscretionary' '202': $ref: '#/components/responses/AckNoCallback' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /on_update: post: summary: PN returns the updated contract description: "The PN calls this endpoint on the CN, delivering the updated\ \ contract state. When responding to a preview request (context.try was true),\ \ the PN returns recalculated terms without having changed any state. When\ \ responding to a committed update (context.try was false) or sending a proactive\ \ PN-initiated mutation, the PN returns the confirmed updated contract.\n\ \nAdditional preconditions: Either an /update request MUST have been sent by\ \ the CN and accepted (200 Ack) by the PN, or the PN is sending a proactive\ \ update for a PN-initiated contract mutation on an already-confirmed\ \ contract.\n\nThe message MUST contain an OnUpdateAction with the Contract\ \ object. The context.try field echoes the value from the originating /update\ \ request to allow the CN to interpret whether this is a preview or a committed\ \ change.\n\nCallback relationship: This endpoint is triggered by the PN either\ \ in response to an /update request or proactively for PN-initiated mutations.\ \ The CN MUST use the messageId in Context to correlate solicited callbacks\ \ and MUST handle unsolicited callbacks by updating the locally held contract\ \ state.\n\nResponse codes: Ack, NackBadRequest, NackUnauthorized, ServerError." operationId: onUpdate tags: - Fulfillment parameters: - $ref: '#/components/parameters/CallbackAuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: on_update message: $ref: '#/components/schemas/OnUpdateAction' responses: '200': $ref: '#/components/responses/Ack' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /cancel: post: summary: CN requests cancellation of an contract description: "The CN requests full or partial cancellation of an active contract\ \ from the PN, using the context.try two-phase pattern to either preview\ \ cancellation terms or commit the cancellation.\n\nAdditional preconditions:\ \ A /confirm request MUST have completed and the CN MUST hold a confirmed\ \ Contract with a valid id before this endpoint may be called.\n\nThe message\ \ MUST contain a CancelAction with the Contract object whose id identifies\ \ the contract to be cancelled. When context.try is set to true, the CN is\ \ requesting applicable cancellation terms (such as refund policy and penalties)\ \ without committing to cancellation; the PN MUST respond via /on_cancel\ \ with the applicable policy without changing state. When context.try is false\ \ (the default), the CN MUST include context.requestDigest containing the\ \ digest of the on_cancel preview response it received; if context.requestDigest\ \ is absent or does not match, the PN MUST return a NackBadRequest. The PN\ \ MUST cancel the contract and respond with the cancelled contract.\n\nCallback relationship:\ \ After processing the cancellation request, the PN MUST send an /on_cancel\ \ callback to the CN. When context.try was true, the callback carries the\ \ applicable cancellation policy without state change. When context.try was\ \ false, the callback carries the cancelled contract with updated settlement\ \ information. The CN MUST correlate the callback using the messageId from\ \ Context.\n\nResponse codes: Ack, AckNoCallback, NackBadRequest, NackUnauthorized,\ \ ServerError." operationId: cancel tags: - Fulfillment parameters: - $ref: '#/components/parameters/AuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: cancel message: $ref: '#/components/schemas/CancelAction' responses: '200': $ref: '#/components/responses/Ack' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '403': $ref: '#/components/responses/NackDiscretionary' '202': $ref: '#/components/responses/AckNoCallback' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /on_cancel: post: summary: PN returns cancellation terms or confirms cancellation description: "The PN calls this endpoint on the CN, delivering either the\ \ applicable cancellation policy (when responding to a preview request) or\ \ the confirmed cancelled contract (when responding to a committed cancellation).\n\ \nAdditional preconditions: A /cancel request MUST have been sent by the CN\ \ and accepted (200 Ack) by the PN before this callback is triggered.\n\n\ The message MUST contain an OnCancelAction with the Contract object. When context.try\ \ was true in the originating /cancel request, the Contract carries cancellation\ \ policy, fees, and refund timeline without state change. When context.try\ \ was false, the Contract carries status CANCELLED and updated settlement information\ \ reflecting any refunds or penalties.\n\nCallback relationship: This endpoint\ \ is triggered by the PN in response to a /cancel request. The CN MUST use\ \ the messageId in Context to correlate this callback. When this is a preview\ \ response, the CN SHOULD present the cancellation terms to the consumer before\ \ calling /cancel with context.try set to false.\n\nResponse codes: Ack, NackBadRequest,\ \ NackUnauthorized, ServerError." operationId: onCancel tags: - Fulfillment parameters: - $ref: '#/components/parameters/CallbackAuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: on_cancel message: $ref: '#/components/schemas/OnCancelAction' responses: '200': $ref: '#/components/responses/Ack' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /rate: post: summary: CN submits ratings for one or more entities description: "The CN submits one or more rating inputs to the PN for ratable\ \ entities associated with a completed contract, including the contract itself,\ \ performance stages, individual resources, the provider, agents, and support\ \ interactions.\n\nAdditional preconditions: The contract for which ratings\ \ are being submitted MUST have reached a terminal state (COMPLETE or CANCELLED)\ \ and the CN MUST hold the confirmed Contract id.\n\nThe message MUST contain\ \ a RateAction with a ratingInputs array. Each RatingInput MUST identify the\ \ target entity being rated. The PN MUST record the submitted ratings.\n\n\ Callback relationship: After processing the rating, the PN MUST send an /on_rate\ \ callback to the CN confirming the ratings were recorded and optionally returning\ \ an aggregate rating snapshot. The CN MUST correlate the callback using the\ \ messageId from Context.\n\nResponse codes: Ack, AckNoCallback, NackBadRequest,\ \ NackUnauthorized, ServerError." operationId: rate tags: - Post-Fulfillment parameters: - $ref: '#/components/parameters/AuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: rate message: $ref: '#/components/schemas/RateAction' responses: '200': $ref: '#/components/responses/Ack' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '403': $ref: '#/components/responses/NackDiscretionary' '202': $ref: '#/components/responses/AckNoCallback' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /on_rate: post: summary: PN acknowledges rating and optionally returns aggregate description: "The PN calls this endpoint on the CN, confirming that the submitted\ \ ratings have been recorded and optionally returning aggregate rating data.\n\ \nAdditional preconditions: A /rate request MUST have been sent by the CN\ \ and accepted (200 Ack) by the PN before this callback is triggered.\n\n\ The message MUST contain an OnRateAction with a ratings array carrying confirmation\ \ of the recorded ratings and MAY include aggregate rating snapshots for the\ \ rated entities.\n\nCallback relationship: This endpoint is triggered by the\ \ PN in response to a /rate request. The CN MUST use the messageId in Context\ \ to correlate this callback with the originating /rate call.\n\nResponse codes:\ \ Ack, NackBadRequest, NackUnauthorized, ServerError." operationId: onRate tags: - Post-Fulfillment parameters: - $ref: '#/components/parameters/CallbackAuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: on_rate message: $ref: '#/components/schemas/OnRateAction' responses: '200': $ref: '#/components/responses/Ack' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /support: post: summary: CN requests support information for an entity description: "The CN requests support from the PN for any entity associated\ \ with a contract by submitting a support request that the PN uses to create\ \ or link a support ticket.\n\nAdditional preconditions: The CN MUST hold\ \ a confirmed Contract id or a reference to another supported entity before\ \ this endpoint may be called.\n\nThe message MUST contain a SupportAction\ \ with a Support object that describes the nature of support needed and the\ \ reference to the entity requiring support. The Support object is not limited\ \ to contracts and MAY reference resources, providers, or agents. The PN MUST\ \ create or link a support ticket and return the details.\n\nCallback relationship:\ \ After processing the support request, the PN MUST send an /on_support callback\ \ to the CN returning support contact details and the created or linked ticket\ \ information. The CN MUST correlate the callback using the messageId from\ \ Context.\n\nResponse codes: Ack, AckNoCallback, NackBadRequest, NackUnauthorized,\ \ ServerError." operationId: support tags: - Post-Fulfillment parameters: - $ref: '#/components/parameters/AuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: support message: $ref: '#/components/schemas/SupportAction' responses: '200': $ref: '#/components/responses/Ack' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '403': $ref: '#/components/responses/NackDiscretionary' '202': $ref: '#/components/responses/AckNoCallback' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /on_support: post: summary: PN returns support details description: "The PN calls this endpoint on the CN, delivering the full support\ \ contact details including the created or linked ticket information.\n\nAdditional\ \ preconditions: A /support request MUST have been sent by the CN and accepted\ \ (200 Ack) by the PN before this callback is triggered.\n\nThe message MUST\ \ contain an OnSupportAction with a Support object carrying support contact\ \ details and the created or linked ticket reference.\n\nCallback relationship:\ \ This endpoint is triggered by the PN in response to a /support request.\ \ The CN MUST use the messageId in Context to correlate this callback with\ \ the originating /support call and SHOULD present the support information\ \ to the consumer.\n\nResponse codes: Ack, NackBadRequest, NackUnauthorized,\ \ ServerError." operationId: onSupport tags: - Post-Fulfillment parameters: - $ref: '#/components/parameters/CallbackAuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: on_support message: $ref: '#/components/schemas/OnSupportAction' responses: '200': $ref: '#/components/responses/Ack' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /catalog/publish: post: summary: PN publishes catalogs for indexing by the CS description: "The PN submits one or more Catalog objects to the CS (Cataloging\ \ Service) for validation and indexing so that CNs may discover them via /discover.\n\ \nAdditional preconditions: At least one Catalog object MUST be present in\ \ the message.\n\nThe message MUST contain a CatalogPublishAction with a non-empty catalogs array.\ \ Each Catalog MUST include an id, descriptor, and provider.\n\nCallback relationship:\ \ After indexing each submitted catalog, the CS sends a /catalog/on_publish\ \ callback to the PN carrying a CatalogOnPublishAction with per-catalog processing\ \ results (ACCEPTED, REJECTED, or PARTIAL). The PN MUST correlate the callback\ \ using the messageId from Context.\n\nA 200 Ack confirms the request was\ \ accepted for processing; the CS will deliver per-catalog results asynchronously\ \ via /catalog/on_publish. A 400 NackBadRequest is returned when the\ \ payload fails schema validation or the catalogs array is empty or missing.\ \ A 401 NackUnauthorized is returned when the Authorization header signature\ \ is missing or invalid. A 500 ServerError indicates an unexpected CS failure;\ \ the PN SHOULD retry." operationId: catalogPublish deprecated: true tags: - Fabric API - Cataloging Service parameters: - $ref: '#/components/parameters/AuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: catalog/publish message: $ref: '#/components/schemas/CatalogPublishAction' examples: simplePublish: summary: Publish a catalog without publishDirectives (resources only, no offers — treated as master) value: context: version: '2.0.0' action: catalog/publish messageId: 550e8400-e29b-41d4-a716-446655440000 transactionId: 550e8400-e29b-41d4-a716-446655440001 timestamp: '2026-03-04T10:00:00.000Z' bppId: bpp.techmart.com bppUri: https://bpp.techmart.com networkId: retail-network message: catalogs: - id: CAT-TECHMART-2026 descriptor: name: TechMart Product Catalog provider: id: provider-techmart-001 descriptor: name: TechMart Electronics resources: - id: ITEM-LAPTOP-001 descriptor: name: Premium Laptop Pro resourceAttributes: '@context': https://schema.beckn.org/retail/schema/1.1.0/context.jsonld '@type': ElectronicsItem brand: TechBrand inStock: true masterCatalogPublish: summary: Publish a master catalog with FULL update mode value: context: version: '2.0.0' action: catalog/publish messageId: 660e8400-e29b-41d4-a716-446655440002 transactionId: 660e8400-e29b-41d4-a716-446655440003 timestamp: '2026-03-04T09:00:00.000Z' bppId: manufacturer.example.com bppUri: https://manufacturer.example.com networkId: retail-network message: publishDirectives: - catalogId: MASTER-ELECTRONICS-2026 visibleTo: - retail-network catalogType: MASTER updateMode: FULL catalogs: - id: MASTER-ELECTRONICS-2026 descriptor: name: Official Electronics Master Catalog 2026 provider: id: manufacturer-001 descriptor: name: Global Electronics Authority resources: - id: MASTER-LAPTOP-XPS-15 descriptor: name: XPS 15 Laptop shortDesc: '15.6-inch FHD+ display, Intel Core i7, 16GB RAM, 512GB SSD' resourceAttributes: '@context': https://schema.beckn.org/retail/schema/1.1.0/context.jsonld '@type': ElectronicsItem brand: Dell model: XPS 15 9530 processor: Intel Core i7-13700H regularExtendingMaster: summary: Regular catalog extending a master resource value: context: version: '2.0.0' action: catalog/publish messageId: 770e8400-e29b-41d4-a716-446655440004 transactionId: 770e8400-e29b-41d4-a716-446655440005 timestamp: '2026-03-04T10:00:00.000Z' bppId: bpp.techmart.com bppUri: https://bpp.techmart.com networkId: retail-network message: publishDirectives: - catalogId: CAT-TECHMART-2026 catalogType: REGULAR updateMode: MERGE resourceDirectives: - resourceId: ITEM-LAPTOP-XPS-15-TECHMART extends: masterResourceId: MASTER-LAPTOP-XPS-15 catalogs: - id: CAT-TECHMART-2026 descriptor: name: TechMart Product Catalog provider: id: provider-techmart-001 descriptor: name: TechMart Electronics resources: - id: ITEM-LAPTOP-XPS-15-TECHMART descriptor: name: XPS 15 - TechMart Edition resourceAttributes: '@context': https://schema.beckn.org/retail/schema/1.1.0/context.jsonld '@type': ElectronicsItem inStock: true deliveryEstimate: 3-5 business days regularWithVariant: summary: Regular catalog with a geographic variant of a master resource value: context: version: '2.0.0' action: catalog/publish messageId: 880e8400-e29b-41d4-a716-446655440006 transactionId: 880e8400-e29b-41d4-a716-446655440007 timestamp: '2026-03-04T11:00:00.000Z' bppId: bpp.freshmart.com bppUri: https://bpp.freshmart.com networkId: grocery-network message: publishDirectives: - catalogId: CAT-FRESHMART-2026 visibleTo: - grocery-network - hyperlocal-network catalogType: REGULAR updateMode: MERGE resourceDirectives: - resourceId: ITEM-RICE-FRESHMART-BLR extends: masterResourceId: MASTER-RICE-BASMATI-1KG variant: type: geo id: bangalore label: Bangalore region catalogs: - id: CAT-FRESHMART-2026 descriptor: name: FreshMart Grocery Catalog provider: id: provider-freshmart-001 descriptor: name: FreshMart Groceries resources: - id: ITEM-RICE-FRESHMART-BLR resourceAttributes: '@context': https://schema.beckn.org/grocery/schema/1.0.0/context.jsonld '@type': GroceryItem deliveryEstimate: same-day localWarehouse: true offerOnlyPublish: summary: Offer-only catalog (pricing offers referencing master resources) value: context: version: '2.0.0' action: catalog/publish messageId: 990e8400-e29b-41d4-a716-446655440008 transactionId: 990e8400-e29b-41d4-a716-446655440009 timestamp: '2026-03-04T12:00:00.000Z' bppId: bpp.techmart.com bppUri: https://bpp.techmart.com networkId: retail-network message: publishDirectives: - catalogId: CAT-TECHMART-OFFERS-2026 catalogType: REGULAR updateMode: MERGE catalogs: - id: CAT-TECHMART-OFFERS-2026 descriptor: name: TechMart Seasonal Offers provider: id: provider-techmart-001 descriptor: name: TechMart Electronics offers: - id: OFFER-LAPTOP-SALE-APR descriptor: name: April Laptop Sale resourceIds: - MASTER-LAPTOP-XPS-15 validity: startDate: '2026-04-01' endDate: '2026-04-30' offerAttributes: '@context': https://schema.beckn.org/retail/schema/1.1.0/context.jsonld '@type': DiscountOffer discountPercent: 15 responses: '200': $ref: '#/components/responses/Ack' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '403': $ref: '#/components/responses/NackDiscretionary' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /catalog/on_publish: post: summary: CS returns per-catalog processing results to the PN description: "The CS (Cataloging Service) calls this endpoint on the PN, delivering\ \ per-catalog processing results for each catalog submitted in a prior /catalog/publish\ \ request.\n\nAdditional preconditions: A /catalog/publish request MUST have\ \ been sent by the PN and accepted (200 Ack) by the CS before this callback\ \ is triggered.\n\nThe message MUST contain a CatalogOnPublishAction\ \ with a results array. Each result carries the catalogId and a processing\ \ status of ACCEPTED, REJECTED, or PARTIAL, along with any per-item errors.\n\ \nCallback relationship: Triggered by the CS after indexing each catalog from\ \ /catalog/publish. The PN MUST use the messageId in Context to correlate\ \ this callback with the originating publish request, and MUST handle REJECTED\ \ or PARTIAL results by correcting and resubmitting affected catalogs.\n\n\ Response codes: Ack, NackBadRequest, NackUnauthorized, ServerError." operationId: catalogOnPublish deprecated: true tags: - Fabric API - Cataloging Service parameters: - $ref: '#/components/parameters/CallbackAuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: catalog/on_publish message: $ref: '#/components/schemas/CatalogOnPublishAction' responses: '200': $ref: '#/components/responses/Ack' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /catalog/push: post: summary: CS pushes catalog updates to a Network Participant description: "The CS (Cataloging Service) calls this endpoint on the DS\ \ to deliver catalog updates that match an active subscription.\n\ \nAdditional preconditions: An active subscription MUST exist for the DS\ \ matching the catalog's networkId and schema types. The DS MUST\ \ have a valid endpoint registered in the network.\n\nAuthentication note: This endpoint uses AuthorizationHeader\ \ (not CallbackAuthorizationHeader) because the CS initiates the push\ \ autonomously when a subscription matches — there is no prior DS request\ \ whose signature could be chained via request-signature. This is analogous\ \ to a PN-initiated notification.\n\nThe message MUST contain a CatalogPublishAction\ \ with a non-empty catalogs array.\n\nA 200 Ack confirms the push was received\ \ and accepted for processing. A 400 NackBadRequest is returned for an invalid\ \ or malformed payload. A 401 NackUnauthorized is returned when the Authorization\ \ header signature is invalid. A 202 AckNoCallback is returned when the receiver\ \ accepted the request but will not process it further (e.g., no matching\ \ subscriptions). A 500 ServerError indicates an unexpected failure at the\ \ DS." operationId: catalogPush deprecated: true tags: - Fabric API - Cataloging Service parameters: - $ref: '#/components/parameters/AuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: catalog/push message: $ref: '#/components/schemas/CatalogPublishAction' responses: '200': $ref: '#/components/responses/Ack' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '202': $ref: '#/components/responses/AckNoCallback' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /catalog/subscription: post: summary: DS subscribes to catalog updates on the CS description: "Creates a new catalog subscription or updates an existing one\ \ on the CS (Cataloging Service). The DS declares which networks and schema\ \ types it wishes to receive ongoing catalog/push callbacks for when matching\ \ catalogs are indexed.\n\nAdditional preconditions: At least one networkId\ \ or schemaType MUST be provided (anyOf). An empty schemaTypes array is treated\ \ as a wildcard matching all schema types for the specified networks. The\ \ DS identity is extracted from the Authorization header.\n\nThe message\ \ MUST contain a CatalogSubscribeAction with a subscription object specifying\ \ networkIds and optional schemaTypes.\n\nA 200 response returns the created\ \ or updated CatalogSubscription in a CatalogSubscriptionResponse envelope.\ \ This endpoint is synchronous — no callback is delivered. A 400 NackBadRequest\ \ is returned when neither networkIds nor schemaTypes is provided, or when\ \ the payload is malformed. A 401 NackUnauthorized is returned when the Authorization\ \ header signature is missing or invalid. A 403 NackForbidden is returned\ \ when the subscriptionId belongs to a different subscriber. A 404 NackNotFound\ \ is returned when the provided subscriptionId does not exist. A 409 NackConflict\ \ is returned when an identical networkIds+schemaTypes combination is already\ \ active for this subscriber. A 500 ServerError indicates an unexpected CS\ \ failure." operationId: catalogSubscribe deprecated: true tags: - Fabric API - Cataloging Service parameters: - $ref: '#/components/parameters/AuthorizationHeader' - name: subscriptionId in: query required: false description: >- When provided, updates the existing subscription with this ID instead of creating a new one. The caller must be the subscription owner. schema: type: string format: uuid example: f47ac10b-58cc-4372-a567-0e02b2c3d479 requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: catalog/subscription message: $ref: '#/components/schemas/CatalogSubscribeAction' example: context: version: 2.0.0 action: catalog/subscription messageId: 550e8400-e29b-41d4-a716-446655440000 transactionId: 550e8400-e29b-41d4-a716-446655440001 timestamp: '2026-03-23T10:00:00.000Z' bapId: bap.example.com bapUri: https://bap.example.com message: subscription: networkIds: - retail schemaTypes: - https://schema.beckn.org/retail/schema/1.1.0/item.json#ItemType responses: '200': description: Subscription created or updated successfully. content: application/json: schema: $ref: '#/components/schemas/CatalogSubscriptionResponse' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '403': $ref: '#/components/responses/NackForbidden' '404': $ref: '#/components/responses/NackNotFound' '409': $ref: '#/components/responses/NackConflict' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' delete: summary: DS deactivates a catalog subscription on the CS operationId: catalogSubscriptionDeactivate deprecated: true tags: - Fabric API - Cataloging Service description: "The DS deactivates an existing subscription on the CS (Cataloging\ \ Service). A deactivated subscription stops receiving catalog updates.\n\ \nAdditional preconditions: The subscriptionId query parameter MUST be provided.\ \ The caller MUST be the subscription owner — the signing key identity in\ \ the Authorization header MUST match the identity used when the subscription\ \ was created.\n\nA 200 response returns the deactivated CatalogSubscription \ \ in a CatalogSubscriptionResponse envelope.\ \ This endpoint is synchronous — no callback is delivered. The subscription\ \ can be reactivated at any time via POST to /catalog/subscription with the\ \ same subscriptionId. A 400 NackBadRequest is returned when the subscriptionId\ \ query parameter is missing or not a valid UUID. A 401 NackUnauthorized is\ \ returned when the Authorization header signature is missing or invalid.\ \ A 403 NackForbidden is returned when the subscription belongs to a different\ \ subscriber. A 404 NackNotFound is returned when the subscriptionId does\ \ not exist. A 500 ServerError indicates an unexpected CS failure." parameters: - $ref: '#/components/parameters/AuthorizationHeader' - name: subscriptionId in: query required: true description: UUID of the subscription to deactivate. schema: type: string format: uuid example: f47ac10b-58cc-4372-a567-0e02b2c3d479 responses: '200': description: Subscription deactivated successfully. content: application/json: schema: $ref: '#/components/schemas/CatalogSubscriptionResponse' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '403': $ref: '#/components/responses/NackForbidden' '404': $ref: '#/components/responses/NackNotFound' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' get: summary: CS returns catalog subscriptions for the DS description: "The DS retrieves its own subscriptions from the CS (Cataloging\ \ Service), optionally filtered by subscription ID or status, with support\ \ for pagination.\n\nAdditional preconditions: The caller's identity\ \ is extracted from the Authorization header. Only subscriptions owned\ \ by the calling DS are returned.\n\nA 200 response\ \ returns a CatalogSubscriptionResponse envelope containing the matching subscriptions\ \ and pagination metadata. When subscriptionId is provided, at most one subscription\ \ is returned. When status is omitted, subscriptions of all statuses are returned.\ \ A 400 NackBadRequest is returned for an invalid subscriptionId format or\ \ out-of-range pagination parameters. A 401 NackUnauthorized is returned when\ \ the Authorization header signature is missing or invalid. A 404 NackNotFound\ \ is returned when a specific subscriptionId was requested but does not exist.\ \ A 500 ServerError indicates an unexpected CS failure." operationId: catalogSubscribeList deprecated: true tags: - Fabric API - Cataloging Service parameters: - $ref: '#/components/parameters/AuthorizationHeader' - name: subscriptionId in: query required: false description: Return a single subscription by its subscription ID. schema: type: string format: uuid example: f47ac10b-58cc-4372-a567-0e02b2c3d479 - name: status in: query required: false description: Filter by subscription status. Returns all statuses when omitted. schema: type: string enum: - ACTIVE - INACTIVE - name: limit in: query required: false description: Page size (default 20, max 100). schema: type: integer minimum: 1 maximum: 100 default: 20 - name: offset in: query required: false description: Pagination offset (default 0). schema: type: integer minimum: 0 default: 0 responses: '200': description: Matching subscriptions with pagination metadata. content: application/json: schema: $ref: '#/components/schemas/CatalogSubscriptionResponse' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '404': $ref: '#/components/responses/NackNotFound' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /catalog/pull: post: summary: DS submits async catalog pull request to the CS description: "The DS submits an asynchronous catalog pull request to the CS\ \ (Cataloging Service), scoped to an active subscription. The subscription's\ \ networkIds and schemaTypes determine which catalogs are returned — they\ \ are not specified on this request.\n\nAdditional preconditions: context.version,\ \ context.action, context.transactionId, and message.subscriptionId MUST be\ \ supplied.\n\nThe message MUST contain a CatalogPullAction. The mode field\ \ MUST be either FULL (returns the latest version of each matching catalog)\ \ or INCREMENTAL (returns all catalog versions published between fromDate and\ \ toDate inclusive).\n\nCallback\ \ relationship: The CS processes the pull request asynchronously and delivers\ \ results via POST to the /catalog/on_pull callback. When the payload is\ \ small it is returned inline; when the result is too large to return inline\ \ the callback carries a downloadManifest for downloading the result.\ \ The DS MUST use context.messageId to correlate the /catalog/on_pull\ \ callback with the originating request.\n\nA 200 Ack confirms the pull request was accepted;\ \ results will be delivered asynchronously via /catalog/on_pull. A 400 NackBadRequest\ \ is returned when the subscriptionId is missing or not a valid UUID, or when\ \ the mode, fromDate, or toDate values are invalid. A 401 NackUnauthorized\ \ is returned when the Authorization header signature is missing or invalid.\ \ A 403 NackForbidden is returned when the subscriptionId does not belong\ \ to the calling DS. A 404 NackNotFound is returned when the subscriptionId\ \ does not exist. A 500 ServerError indicates an unexpected CS failure; the\ \ DS SHOULD retry." operationId: catalogPull deprecated: true tags: - Fabric API - Cataloging Service parameters: - $ref: '#/components/parameters/AuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object required: - transactionId properties: action: type: string const: catalog/pull message: $ref: '#/components/schemas/CatalogPullAction' responses: '200': description: ACK — pull request accepted; result will be delivered asynchronously via callback content: application/json: schema: type: object required: - status properties: status: type: string const: ACK '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '403': $ref: '#/components/responses/NackForbidden' '404': $ref: '#/components/responses/NackNotFound' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /catalog/on_pull: post: summary: CS delivers historical catalog versions to the DS description: "The CS (Cataloging Service) calls this endpoint on the DS \ \ to deliver the results of a previously accepted /catalog/pull \ \ request.\n\nAdditional preconditions: A /catalog/pull request MUST have\ \ been sent by the DS and accepted (200 Ack) by the CS before this callback\ \ is triggered. The DS MUST use context.messageId to correlate\ \ this callback with the originating /catalog/pull request.\n\n \ The message MUST contain a CatalogPullCallbackAction with \ \ a status of COMPLETED or FAILED,\ \ and either an inline catalogs array (small payload) or a downloadManifest\ \ for downloading the result (large payload).\n\nA 200 Ack confirms the callback\ \ was received and accepted by the DS. A 400 NackBadRequest is returned\ \ when the payload is malformed or required fields are missing. A 401 NackUnauthorized\ \ is returned when the Authorization header (callback) signature is invalid.\ \ A 500 ServerError indicates an unexpected DS failure." operationId: catalogOnPull deprecated: true tags: - Fabric API - Cataloging Service parameters: - $ref: '#/components/parameters/CallbackAuthorizationHeader' requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: catalog/on_pull message: $ref: '#/components/schemas/CatalogPullCallbackAction' responses: '200': $ref: '#/components/responses/Ack' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' /catalog/search: post: summary: PN searches catalogs on the CS description: "The PN queries the CS (Cataloging Service) for indexed\ \ catalogs, filtered by catalog type, network identifiers, and schema type\ \ URIs with paginated results.\n\nAdditional preconditions: All filters are\ \ optional. Omitting filters.type defaults to MASTER. Omitting\ \ or leaving filters.networkIds empty matches all networks. Omitting or leaving\ \ filters.schemaTypes empty matches all schema types. limit MUST be between\ \ 1 and 100 (default 20); offset MUST be non-negative (default 0).\n\nThe message MUST contain\ \ a CatalogSearchAction with optional filters and optional pagination parameters.\ \ All responses are wrapped in a Beckn envelope with action set to\ \ \"catalog/on_search\".\n\nA 200 response returns the matching catalog items\ \ directly in a catalogs array. A 400 NackBadRequest is returned for an\ \ invalid payload or out-of-range pagination parameters. A 401 NackUnauthorized\ \ is returned when the Authorization header signature is missing or invalid.\ \ A 429 NackTooManyRequests is returned when the request rate exceeds the\ \ CS rate limit. A 500 ServerError indicates an unexpected CS failure." operationId: catalogSearch deprecated: true tags: - Fabric API - Cataloging Service parameters: - $ref: '#/components/parameters/AuthorizationHeader' requestBody: required: true content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: catalog/search message: $ref: '#/components/schemas/CatalogSearchAction' responses: '200': description: Master search results content: application/json: schema: type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: catalog/on_search message: type: object required: - catalogs - pagination properties: catalogs: type: array items: $ref: '#/components/schemas/Catalog' pagination: $ref: '#/components/schemas/Pagination' '400': $ref: '#/components/responses/NackBadRequest' '401': $ref: '#/components/responses/NackUnauthorized' '429': $ref: '#/components/responses/NackTooManyRequests' '500': $ref: '#/components/responses/ServerError' components: parameters: AuthorizationHeader: name: Authorization in: header required: true description: "Beckn HTTP Signature authentication header for CN requests and\ \ PN-initiated callbacks. The signing string covers `(created)`,\ \ `(expires)`, and the BLAKE2b-512 body digest.\n\nSee `#/components/schemas/Signature`\ \ for the wire format and signing string construction. For PN solicited callbacks,\ \ use `CallbackAuthorizationHeader` instead." schema: $ref: '#/components/schemas/Signature' CallbackAuthorizationHeader: name: Authorization in: header required: true description: "Beckn HTTP Callback Signature authentication header for PN solicited\ \ callbacks to CN `/on_*` endpoints. The signing string covers `(created)`,\ \ `(expires)`, the BLAKE2b-512 body digest, and `request-signature` — the\ \ raw Base64 signature value from the triggering CN request's `Authorization`\ \ header. This chain proves the callback is a genuine response to the CN's\ \ original request.\n\nEndpoints that also accept PN-initiated callbacks\ \ (no preceding CN request) use `AuthorizationHeader` with the standard\ \ Signature for those messages.\n\nSee `#/components/schemas/CallbackSignature`\ \ for the wire format and signing string construction." schema: $ref: '#/components/schemas/CallbackSignature' headers: AckSignatureHeader: description: "Beckn HTTP Ack Signature response header transmitted on every\ \ synchronous response. The signer is the responding NP (PN or CN); the\ \ receiver verifies it to confirm authenticated receipt. The signing string\ \ chains the responder's signature to the incoming request's Authorization\ \ signature via the `request-signature` field, cryptographically proving the\ \ responder was in possession of the specific inbound request.\n\nSee `#/components/schemas/AckSignature`\ \ for the wire format and signing string construction. See NFH-004 Authentication\ \ and Trust §5 for the full signing procedure." required: true schema: $ref: '#/components/schemas/AckSignature' schemas: CancelAction: title: Cancel Action description: "The real-world act by which the CN expresses the consumer's\ \ intent to cancel an active contract, optionally entering a preview phase\ \ to retrieve applicable cancellation terms before committing to the cancellation.\n\ \nThis schema appears in the performance and post-performance phases of the\ \ value-exchange lifecycle. The CN produces it as the message payload of a\ \ /cancel request; the PN consumes it to determine whether to preview cancellation\ \ terms (context.try true) or execute the cancellation (context.try false).\n\ \nRelationship: Composes the Contract schema as its primary carrier. The Contract\ \ MUST include an id identifying the active contract to be cancelled." properties: contract: allOf: - $ref: '#/components/schemas/Contract' - required: - id required: - contract CatalogPublishAction: deprecated: true description: "The real-world act by which a PN submits one or more catalogs\ \ to the CS (Cataloging Service) for indexing so that CNs may subsequently\ \ discover them.\n\nThis schema appears in the Catalog Publishing phase of\ \ the value-exchange lifecycle. The PN produces it as the message payload\ \ of a /catalog/publish request; the CS consumes it to index the provided\ \ catalogs into its catalog store.\n\nRelationship: Composes one or more Catalog schemas in the catalogs array.\ \ The optional publishDirectives array controls per-catalog processing —\ \ catalog type, update mode, resource inheritance, and visibility." required: - catalogs type: object properties: catalogs: type: array minItems: 1 items: $ref: '#/components/schemas/Catalog' publishDirectives: description: >- Publish directives define per-catalog processing instructions, matched by `catalogId`. When not defined, When not provided, the type is inferred from the catalog content — catalogs with offers are treated as `regular`; catalogs with only resources are treated as `master`. Default update mode is `MERGE`. type: array items: type: object required: - catalogId - catalogType properties: catalogId: type: string description: >- Identifier of the catalog these instructions apply to. MUST exactly match a catalog `id` in the `catalogs` array of this request. example: CAT-SUMMER-TECHMART-2026 visibleTo: type: array items: type: string description: >- Restricts delivery of this catalog to the listed network participant identifiers. Values MUST be registry-registered network participant identifiers. Assigned by the PN; enforced by the CS at delivery time. When omitted, the catalog is visible to all eligible subscribers. example: - retail-network - mobility-network catalogType: type: string enum: - MASTER - REGULAR description: >- Declares the type of this catalog. `MASTER` — Canonical resource definitions reusable across the network. `REGULAR` — Provider-specific catalog that can optionally extend master resources. example: REGULAR updateMode: type: string enum: - FULL - MERGE default: MERGE description: >- Controls how the catalog is updated. `MERGE` (default) — Upserts resources by `id`; existing resources not in this request are retained. `FULL` — Replaces the entire catalog with this request. example: MERGE resourceDirectives: description: >- Links individual resources in a regular catalog to master resources they inherit from, and optionally marks them as variants. Only applies when `catalogType` is `regular`. type: array items: type: object required: - resourceId - extends properties: resourceId: type: string description: >- The provider's resource identifier in this catalog. Must match a resource `id` in the `catalogs` array of this request. example: ITEM-LAPTOP-XPS-15-TECHMART extends: type: object additionalProperties: false required: - masterResourceId description: >- Declares which master resource this provider resource inherits from. properties: masterResourceId: type: string description: >- The `id` of the master resource to inherit from. Must refer to a resource that was previously published in a master catalog within the same network. example: MASTER-LAPTOP-XPS-15 variant: type: object additionalProperties: true description: >- Marks this resource as a named variant of the master resource it extends. The `type` + `id` combination uniquely identifies a variant within a resource. Without this field, the resource is treated as the base version. properties: type: type: string description: >- A category that groups related variants together. Any string value is valid. example: geo id: type: string description: >- Identifier for this specific variant within the given `type`. The combination of `type` + `id` must be unique per resource. example: bangalore label: type: string description: >- A human-readable name for this variant. example: Bangalore region ConfirmAction: title: Confirm Action description: "The real-world act by which the CN expresses the consumer's\ \ unconditional acceptance of all previously negotiated terms and commits to\ \ the contract by providing payment proof or a payment reference, requesting\ \ the PN to convert the draft contract into a binding commitment.\n\nThis\ \ schema appears at the culmination of the negotiation phase of the value-exchange\ \ lifecycle (after discover, select, and init). The CN produces it as the\ \ message payload of a /confirm request; the PN consumes it to verify payment\ \ and activate the contract.\n\nRelationship: Composes the Contract schema\ \ as its primary carrier. The Contract MUST include populated commitments,\ \ participant billing details, and at least one Settlement entry carrying\ \ the payment proof or reference." properties: contract: $ref: '#/components/schemas/Contract' required: - contract DiscoverAction: title: Discover Action (External) description: "The real-world act by which the CN expresses a consumer's intent\ \ to discover products, services, or resources across a Beckn network, encapsulating\ \ all search qualifiers within a structured intent container.\n\nThis schema\ \ appears at the start of the value-exchange lifecycle. The CN produces it\ \ as the message payload of a /discover request; the DS (Discovery Service)\ \ consumes it to evaluate the intent against its indexed catalog store and\ \ return matching results.\n\nFabric context: This schema is evaluated against\ \ the DS's indexed catalog store.\n\nRelationship: Composes the Intent schema\ \ as its primary carrier. The intent property is required and contains all\ \ structured search qualifiers including textSearch, JSONPath filters, spatial\ \ constraints, and media search inputs. The legacy snake_case text_search\ \ property previously exposed by this schema has been removed; structured\ \ search inputs are now expressed exclusively via the intent container." type: object properties: intent: $ref: '#/components/schemas/Intent' additionalProperties: false required: - intent InitAction: title: Init Action description: "The real-world act by which the CN provides the consumer's billing\ \ details, fulfillment preferences, and initial payment intent to the PN,\ \ enabling the PN to generate a final draft contract with personalized payment\ \ terms.\n\nThis schema appears in the negotiation phase of the value-exchange\ \ lifecycle, between the select and confirm steps. The CN produces it as\ \ the message payload of an /init request; the PN consumes it to finalize\ \ contract terms and payment conditions.\n\nRelationship: Composes the Contract\ \ schema as its primary carrier. The Contract MUST include participant billing\ \ details and performance preferences reflecting the consumer's fulfillment\ \ requirements." additionalProperties: false properties: contract: $ref: '#/components/schemas/Contract' required: - contract OnCancelAction: title: On Cancel Action description: "The real-world act by which the PN returns the outcome of a\ \ cancellation request to the CN, either presenting the applicable cancellation\ \ policy when in preview mode or confirming the executed cancellation with\ \ the terminal contract state.\n\nThis schema appears in the performance and\ \ post-performance phases of the value-exchange lifecycle. The PN produces\ \ it as the message payload of an /on_cancel callback; the CN consumes it\ \ to inform the consumer of cancellation terms or to update the locally held\ \ contract state to CANCELLED.\n\nRelationship: Composes the Contract schema\ \ as its primary carrier. When cancellation has been executed, the Contract\ \ status code MUST be CANCELLED and the settlements array MUST reflect any\ \ applicable refunds or penalties." additionalProperties: false properties: contract: $ref: '#/components/schemas/Contract' required: - contract OnConfirmAction: title: OnConfirmAction description: "The real-world act by which the PN delivers the confirmed and\ \ active contract to the CN, including the PN-assigned contract identifier\ \ and initial performance state, after verifying the consumer's payment and\ \ activating the commitment.\n\nThis schema appears at the conclusion of the\ \ negotiation phase of the value-exchange lifecycle. The PN produces it as\ \ the message payload of an /on_confirm callback; the CN consumes it to inform\ \ the consumer that the transaction is confirmed and to store the contract\ \ id for subsequent lifecycle interactions.\n\nRelationship: Composes the\ \ Contract schema as its primary carrier. The Contract status code MUST be\ \ ACTIVE, the id field MUST carry the PN-assigned contract identifier, and\ \ the performance array MUST reflect the initial fulfillment state." additionalProperties: false properties: contract: $ref: '#/components/schemas/Contract' required: - contract OnDiscoverAction: description: "The real-world act by which the DS (Discovery Service) returns\ \ catalogs matching the consumer's discovery intent to the CN, completing\ \ the discovery exchange.\n\nThis schema appears at the start of the value-exchange\ \ lifecycle, immediately following the discovery request. The DS produces\ \ it as the message payload of an /on_discover callback; the CN consumes\ \ it to present discovered providers and their offerings to the consumer.\n\ \nFabric context: The catalogs array is assembled from the DS's indexed catalog\ \ store.\n\nRelationship: Composes one or more Catalog schemas in the required\ \ catalogs array. Each Catalog carries a provider, resources, and offers matching\ \ the original intent." type: object required: - catalogs properties: catalogs: type: array description: 'Array of catalogs matching the discovery request. Array of catalogs matching the discovery request.' items: $ref: '#/components/schemas/Catalog' additionalProperties: false OnInitAction: title: On Init Action description: "The real-world act by which the PN delivers the final draft contract\ \ to the CN, including personalized payment terms, billing confirmation, and\ \ settlement conditions that the consumer must accept before confirming the\ \ transaction.\n\nThis schema appears in the negotiation phase of the value-exchange\ \ lifecycle, between init and confirm. The PN produces it as the message\ \ payload of an /on_init callback; the CN consumes it to present the final\ \ terms to the consumer for acceptance.\n\nRelationship: Composes the Contract\ \ schema as its primary carrier. The Contract MUST include finalized consideration\ \ amounts, payment terms in the settlements array, and billing details reflecting\ \ the consumer's submission." additionalProperties: false properties: contract: $ref: '#/components/schemas/Contract' required: - contract OnRateAction: title: On Rate Action description: "The real-world act by which the PN returns the outcome of a\ \ rating request to the CN, either delivering rating form definitions and\ \ criteria when in preview mode or confirming that the submitted ratings have\ \ been recorded.\n\nThis schema appears in the post-performance phase of the\ \ value-exchange lifecycle. The PN produces it as the message payload of\ \ an /on_rate callback; the CN consumes it to confirm to the consumer that\ \ ratings were accepted or to render the rating form when in preview mode.\n\ \nRelationship: Composes zero or more RatingInput schemas in the required\ \ ratings array. Each RatingInput identifies a rated target entity and carries\ \ the range and optional aggregate data." type: object additionalProperties: false properties: ratings: type: array items: $ref: '#/components/schemas/RatingInput' required: - ratings OnSelectAction: title: On Select Action description: "The real-world act by which the PN delivers a priced quote to\ \ the CN, reflecting the total cost, applicable offers, and terms for the\ \ resources and commitments selected by the consumer.\n\nThis schema appears\ \ in the negotiation phase of the value-exchange lifecycle, between select\ \ and init. The PN produces it as the message payload of an /on_select callback;\ \ the CN consumes it to present the priced quote to the consumer before proceeding\ \ to initiation.\n\nRelationship: Composes the Contract schema as its primary\ \ carrier. The Contract MUST include updated consideration amounts and offer-linked\ \ pricing reflecting the selected resources and quantities." additionalProperties: false properties: contract: $ref: '#/components/schemas/Contract' required: - contract OnStatusAction: title: On Status Action description: "The real-world act by which the PN communicates the current\ \ state of an active contract to the CN, either in response to a status query\ \ or as a proactive push notification for a significant state transition.\n\ \nThis schema appears in the performance phase of the value-exchange lifecycle.\ \ The PN produces it as the message payload of an /on_status callback; the\ \ CN consumes it to update the displayed contract state for the consumer.\ \ This schema covers significant lifecycle state changes only; real-time position\ \ tracking uses Tracking via OnTrackAction.\n\nRelationship: Composes the\ \ Contract schema as its primary carrier. The Contract MUST include the current\ \ status descriptor and updated performance array reflecting the latest fulfillment\ \ state." additionalProperties: false properties: contract: $ref: '#/components/schemas/Contract' required: - contract OnSupportAction: title: On Support Action description: "The real-world act by which the PN returns support information\ \ to the CN, either delivering a list of available support channels when in\ \ preview mode or providing full support contact details and a created or linked\ \ ticket when a support request has been submitted.\n\nThis schema appears\ \ in the post-performance phase of the value-exchange lifecycle. The PN produces\ \ it as the message payload of an /on_support callback; the CN consumes it\ \ to connect the consumer with the appropriate support channel or ticket.\n\ \nRelationship: Composes the Support schema as its primary carrier. The Support\ \ object carries the referenced entity, available channels, and, when a ticket\ \ has been created, the ticket details." additionalProperties: false properties: support: $ref: '#/components/schemas/Support' required: - support OnTrackAction: title: On Track Action description: "The real-world act by which the PN delivers a real-time tracking\ \ handle to the CN, providing the URL or WebSocket endpoint through which\ \ the consumer may monitor live position and progress updates for an active\ \ fulfillment stage.\n\nThis schema appears in the performance phase of the\ \ value-exchange lifecycle. The PN produces it as the message payload of\ \ an /on_track callback; the CN consumes it to open the tracking connection\ \ and expose real-time progress to the consumer.\n\nRelationship: Composes\ \ the Tracking schema as its primary carrier. The Tracking object MUST include\ \ a url for the tracking data source and a status field indicating whether\ \ tracking is ACTIVE or INACTIVE." type: object additionalProperties: false properties: tracking: $ref: '#/components/schemas/Tracking' required: - tracking OnUpdateAction: title: On Update Action description: "The real-world act by which the PN delivers the outcome of a\ \ contract mutation to the CN, either returning recalculated terms without\ \ state change (preview mode) or confirming the committed updated contract\ \ state, which may also be sent proactively for PN-initiated mutations.\n\ \nThis schema appears in the performance phase of the value-exchange lifecycle.\ \ The PN produces it as the message payload of an /on_update callback; the\ \ CN consumes it to update the locally held contract state or to present\ \ revised terms to the consumer before committing.\n\nRelationship: Composes\ \ the Contract schema as its primary carrier. The Contract reflects the updated\ \ state including any changes to commitments, consideration amounts, or performance\ \ details." additionalProperties: false properties: contract: $ref: '#/components/schemas/Contract' required: - contract RateAction: title: RateAction description: "The real-world act by which the CN submits one or more consumer\ \ ratings for entities associated with a completed contract, including the\ \ contract itself, fulfillment stages, individual resources, the provider,\ \ agents, and support interactions.\n\nThis schema appears in the post-performance\ \ phase of the value-exchange lifecycle. The CN produces it as the message\ \ payload of a /rate request; the PN consumes it to record the submitted\ \ ratings.\n\nRelationship: Composes one or more RatingInput schemas in the\ \ required ratingInputs array. Each RatingInput MUST identify the target entity\ \ being rated and MUST include a scoring range." type: object additionalProperties: false properties: ratingInputs: type: array items: $ref: '#/components/schemas/RatingInput' required: - ratingInputs SelectAction: title: Select Action description: "The real-world act by which the CN identifies specific resources\ \ and offers from a discovered catalog and requests the PN to compute a priced\ \ quote, thereby initiating the negotiation cycle.\n\nThis schema appears\ \ in the negotiation phase of the value-exchange lifecycle, immediately following\ \ discovery. The CN produces it as the message payload of a /select request;\ \ the PN consumes it to evaluate availability, compute pricing, and return\ \ a quote via /on_select.\n\nRelationship: Composes the Contract schema as\ \ its primary carrier. The Contract MUST include commitments referencing the\ \ selected resources and associated offers. No PII or billing information\ \ MUST be included at this stage." additionalProperties: false properties: contract: $ref: '#/components/schemas/Contract' required: - contract StatusAction: title: Status Action description: "The real-world act by which the CN polls the PN for the current\ \ state of an active contract by providing its identifier, triggering the\ \ PN to return the latest fulfillment and lifecycle state.\n\nThis schema\ \ appears in the performance phase of the value-exchange lifecycle. The CN\ \ produces it as the message payload of a /status request; the PN consumes\ \ it to locate the contract and return its current state via /on_status. CNs\ \ SHOULD NOT use repeated status calls for continuous monitoring; the PN\ \ MAY push proactive /on_status callbacks for significant state changes.\n\ \nRelationship: Composes the Contract schema as its primary carrier. The Contract\ \ MUST include an id identifying the active contract to be queried." properties: contract: allOf: - $ref: '#/components/schemas/Contract' - required: - id required: - contract SupportAction: title: Support Action description: "The real-world act by which the CN requests support from the\ \ PN for any entity associated with a contract, submitting a support request\ \ that the PN uses to create or link a support ticket.\n\nThis schema appears\ \ in the post-performance phase of the value-exchange lifecycle. The CN produces\ \ it as the message payload of a /support request; the PN consumes it to\ \ create or link a support ticket and return the details.\n\nRelationship:\ \ Composes the Support schema as its primary carrier. The Support object MUST\ \ carry a descriptor describing the nature of the support needed." type: object additionalProperties: false properties: support: $ref: '#/components/schemas/Support' required: - support TrackAction: type: object description: "The real-world act by which the CN requests a real-time tracking\ \ handle from the PN for an active fulfillment or performance stage of a\ \ confirmed contract, enabling the consumer to monitor live position and progress\ \ updates.\n\nThis schema appears in the performance phase of the value-exchange\ \ lifecycle. The CN produces it as the message payload of a /track request;\ \ the PN consumes it to identify the performance stage and return an appropriate\ \ tracking handle via /on_track.\n\nRelationship: Composes the Tracking schema\ \ as its primary carrier. The Tracking object MUST include a contract reference\ \ with an id identifying the active contract whose performance stage is to\ \ be tracked." additionalProperties: false properties: tracking: $ref: '#/components/schemas/Tracking' required: - tracking UpdateAction: title: Update Action description: "The real-world act by which the CN requests a mutation to an\ \ active contract, which may include changes to committed resources, quantities,\ \ billing details, performance preferences, or payment arrangements, using\ \ the context.try pattern to preview or commit the change.\n\nThis schema\ \ appears in the performance phase of the value-exchange lifecycle. The CN\ \ produces it as the message payload of an /update request; the PN consumes\ \ it to compute revised terms (when context.try is true) or to apply and confirm\ \ the mutation (when context.try is false).\n\nRelationship: Composes the\ \ Contract schema as its primary carrier. The Contract MUST include the id\ \ of the active contract being mutated and MUST reflect the desired post-mutation\ \ state of the relevant fields." additionalProperties: false properties: contract: $ref: '#/components/schemas/Contract' required: - contract AddOn: description: "An optional supplementary resource or offer that the consumer\ \ may elect to include alongside a primary committed resource, carrying its\ \ own independent pricing and terms that contribute to the overall contract\ \ consideration.\n\nAdd-ons appear in the negotiation and selection phases\ \ of the value-exchange lifecycle. The PN produces them as part of an Offer\ \ in a Catalog; the CN includes selected add-ons in the commitments of a\ \ Contract during the select and init steps. Add-ons may represent cross-sell\ \ or up-sell items, monetary contributions such as donations, or domain-specific\ \ supplements such as travel insurance, accessibility assistance, or supplementary\ \ services that have no independent existence outside the context of the primary\ \ resource.\n\nRelationship: Defined as a oneOf composed of either a Resource\ \ or an Offer schema, allowing add-ons to model both tangible supplementary\ \ goods and structured offer terms." oneOf: - $ref: '#/components/schemas/Resource' - $ref: '#/components/schemas/Offer' Address: description: "A structured postal address representing the civic location of\ \ a participant, provider, or delivery point, aligned with the schema.org\ \ PostalAddress vocabulary for human-readable addressing.\n\nThis schema appears\ \ wherever a civic address is required across the value-exchange lifecycle,\ \ including participant billing details in InitAction, provider locations in\ \ a Catalog, and delivery destinations in Performance. Both the CN and PN\ \ produce and consume it depending on context.\n\nRelationship: Used as a\ \ component within the Location schema, which also carries geometric coordinates\ \ via the GeoJSONGeometry schema. Geometry MUST be expressed in Location.geo\ \ rather than embedded in Address." title: Address type: object properties: addressCountry: description: Country name or ISO-3166-1 alpha-2 code. type: string example: IN addressLocality: description: City/locality. type: string example: Bengaluru addressRegion: description: State/region/province. type: string example: Karnataka extendedAddress: description: Address extension (apt/suite/floor, C/O). type: string example: Apt 4B postalCode: description: Postal/ZIP code. type: string example: '560001' streetAddress: description: Street address (building name/number and street). type: string example: 123 Tech Street additionalProperties: false AsyncError: title: Asynchronous Error description: "An error condition reported asynchronously within a Beckn callback\ \ when the implementing actor encounters a failure during processing that cannot\ \ be communicated in the synchronous response.\n\nThis schema appears in the\ \ callback phase of any Beckn interaction where an error must be conveyed after\ \ an initial ACK has already been returned. Both the PN and CN MAY produce\ \ it when reporting failures in asynchronous processing to their counterpart.\n\ \nRelationship: Extends the base Error schema with JSON-LD type annotations,\ \ allowing linked-data consumers to interpret error codes using the Beckn error\ \ vocabulary. Additional properties are permitted to carry domain-specific\ \ error context." allOf: - $ref: '#/components/schemas/Error' - type: object properties: {} additionalProperties: true Attributes: description: "A JSON-LD aware extensibility container that carries domain-specific\ \ attributes for any Beckn schema that supports it, enabling domain packs to\ \ add structured, semantically typed fields without modifying the core schema.\n\ \nThis schema appears throughout the value-exchange lifecycle wherever a Beckn\ \ core schema requires domain-specific extension, including Resource.resourceAttributes,\ \ Offer.offerAttributes, Performance.performanceAttributes, Contract.contractAttributes,\ \ and Commitment.commitmentAttributes. Both CNs and PNs produce and consume\ \ it depending on the context in which it appears.\n\nRelationship: Used by\ \ composition throughout the schema hierarchy as the standard extension point.\ \ The @context property MUST reference a valid JSON-LD context URI and the\ \ @type property MUST identify the domain type being expressed." title: Attributes type: object properties: '@context': description: Use case specific JSON-LD context URI type: string '@type': description: JSON-LD type defined within the context type: string required: - '@context' - '@type' additionalProperties: true Catalog: description: "A structured representation of the resources, offers, and provider\ \ information that a PN makes available on the network for discovery, selection,\ \ and commitment by CNs.\n\nCatalogs appear in the discovery phase of the\ \ value-exchange lifecycle. The PN produces them and publishes them to the\ \ CS (Cataloging Service) via CatalogPublishAction; the CS indexes them and\ \ synchronizes them to the DS, which serves them to CNs in OnDiscoverAction\ \ responses. The CS also stores and serves canonical master catalog items\ \ directly.\n\nRelationship:\ \ Composes Provider, Resource, and Offer schemas. MUST include at least one\ \ of a resources array or an offers array. The validity field constrains the\ \ temporal window during which the catalog is active, expressed as a TimePeriod." title: Catalog type: object properties: bppId: description: PN (Beckn Protocol Provider) identifier that publishes this catalog type: string example: bpp.example.com bppUri: description: Beckn Protocol API base URL of the PN type: string format: uri descriptor: description: Human / Agent-readable description of this catalog allOf: - $ref: '#/components/schemas/Descriptor' id: description: Unique identifier for the catalog type: string example: catalog-electronics-001 isActive: description: Whether the catalog is active type: boolean default: true offers: description: Array of offers optionally linked to resources type: array items: $ref: '#/components/schemas/Offer' resources: description: Array of generalized Resource entities in this catalog (new model) type: array items: $ref: '#/components/schemas/Resource' provider: $ref: '#/components/schemas/Provider' validity: description: The time period during which this catalog is valid $ref: '#/components/schemas/TimePeriod' required: - id - descriptor - provider anyOf: - required: - resources - required: - offers additionalProperties: false CatalogOnPublishAction: deprecated: true description: "The real-world act by which the CS (Cataloging Service) communicates\ \ per-catalog processing outcomes to the PN after completing indexing for\ \ each catalog submitted in a publish request.\n\nThis schema appears in the\ \ Catalog Publishing phase of the value-exchange lifecycle. The CS produces\ \ it as the message payload of a /catalog/on_publish callback; the PN consumes\ \ it to determine which submitted catalogs were successfully indexed and which\ \ require correction and resubmission.\n\nRelationship: Composes\ \ one or more CatalogProcessingResult schemas in the required results array,\ \ one per submitted catalog." type: object required: - results properties: results: type: array description: Per-catalog processing results items: $ref: '#/components/schemas/CatalogProcessingResult' CatalogProcessingResult: deprecated: true description: "The outcome record produced by the CS (Cataloging Service) for\ \ a single catalog submission, indicating whether the catalog was accepted,\ \ rejected, or partially indexed, along with any per-item or per-catalog errors.\n\ \nThis schema appears in the CatalogOnPublishAction and is produced by the\ \ CS. The PN consumes it to identify catalogues that require correction.\n\ \nRelationship: Composes zero or more Error schemas in the errors\ \ array when status is REJECTED or PARTIAL. An optional stats object provides\ \ counts of accepted items, providers, and categories." type: object required: - catalogId - status properties: catalogId: type: string description: Identifier of the submitted catalog status: description: 'Processing outcome. Using oneOf [string, object] to allow domain-specific status objects (e.g. beckn:CatalogAccepted) alongside standard string codes.' type: string enum: - ACCEPTED - REJECTED - PARTIAL errors: type: array description: Per-item or per-catalog errors (present when REJECTED or PARTIAL) items: $ref: '#/components/schemas/Error' stats: type: object description: Optional statistics about the processed catalog properties: itemCount: type: integer description: Number of items accepted providerCount: type: integer description: Number of providers in the catalog categoryCount: type: integer description: Number of distinct categories Consideration: type: object description: "A domain-neutral representation of the value agreed to be exchanged\ \ under a contract, which may take the form of monetary payment, credits or\ \ tokens, asset transfer, service exchange, or a compliance artifact depending\ \ on the domain.\n\nConsideration appears across the negotiation phase of\ \ the value-exchange lifecycle, from select through confirm. The PN assigns\ \ consideration amounts in OnSelectAction and OnInitAction; the CN acknowledges\ \ them in ConfirmAction. Both actors produce and consume consideration records\ \ to track value commitment and discharge.\n\nRelationship: Composes the Descriptor\ \ schema for the status field and the Attributes schema for domain-specific\ \ consideration attributes. For monetary considerations, the PriceSpecification\ \ domain schema SHOULD be used within considerationAttributes." required: - id properties: id: description: Identifier of this consideration type: string status: description: > The lifecycle state of this consideration. Required when Consideration appears in Contract.consideration[] from on_select onward. Optional in Offer.considerations[] (catalog context, where no transaction lifecycle has been established) and in select-phase payloads where the Seeker NP signals intent before the Provider NP has priced the consideration. $ref: '#/components/schemas/Descriptor' considerationAttributes: description: 'Domain-specific attributes of this consideration. For monetary considerations, use the PriceSpecification schema to capture total value with breakup. For other consideration types, use a generic Attributes bag.' $ref: '#/components/schemas/Attributes' Context: description: "The message envelope header that accompanies every Beckn API\ \ call, carrying network addressing, protocol version, action identification,\ \ transaction correlation identifiers, timing constraints, and optional cryptographic\ \ metadata required to route, authenticate, and correlate messages across the\ \ asynchronous Beckn communication pattern.\n\nContext appears in every request\ \ and callback across all phases of the value-exchange lifecycle. The CN\ \ assigns bapId, bapUri, transactionId, messageId, and timestamp when originating\ \ a request; the PN assigns bppId and bppUri when it is the receiving actor.\ \ Fabric services such as the CS (Cataloging Service) and DS (Discovery Service)\ \ validate the version, action, and signature fields as part of request authentication.\n\nRelationship: Composes the RequestDigest schema via the\ \ requestDigest property, which carries the BLAKE2b-512 hash of the originating\ \ request body for non-repudiation of the asynchronous callback leg." type: object title: Context properties: action: description: The Beckn protocol method name being invoked by the sender, which the receiving actor MUST use to route and execute the corresponding operation. The value MUST match the action value defined in the path schema for the endpoint being called. type: string version: type: string description: The Beckn protocol version in use for this transaction, assigned by the CN when constructing the request. MUST be the const value 2.0.0 for all requests conforming to this specification. const: 2.0.0 bapId: description: Verified namespace identifier of the CN on dedi.global. Receiving actors MUST resolve the CN's address and key material by first resolving the subnet registry URL from context.networkId, then calling the subnet registry's lookup endpoint with context.bapId and context.networkId. The subscriber_url field in the response is the CN's network address; the key material is used for signature verification. type: string senderId: description: The globally unique decentralized identifier (DID) of the message sender, pointing to a DID document from which the sender's verification keys can be resolved for cryptographic verification. type: string bapUri: description: The callback base URL of the CN to which the PN or Fabric service MUST deliver asynchronous callbacks. This MUST match the subscriber_url returned by the subnet registry lookup for context.bapId and context.networkId. type: string format: uri bppId: description: Verified namespace identifier of the PN on dedi.global. Calling actors MUST resolve the PN's address and key material by first resolving the subnet registry URL from context.networkId, then calling the subnet registry's lookup endpoint with context.bppId and context.networkId. The subscriber_url field in the response is the PN's network address; the key material is used for signature verification. type: string bppUri: description: The request base URL of the PN to which the CN MUST send request API calls. This MUST match the subscriber_url returned by the subnet registry lookup for context.bppId and context.networkId. type: string format: uri receiverId: description: The globally unique decentralized identifier (DID) of the message receiver, pointing to a DID document from which the receiver's verification keys can be resolved for encrypted delivery or targeted routing. type: string transactionId: description: A UUID assigned by the CN that persists across all API calls within a single transaction session from discover through confirm. The PN MAY use this value to correlate related requests, push personalized recommendations, and maintain dynamic offerings across the multi-step negotiation cycle without requiring knowledge of the specific consumer identity on the CN. type: string format: uuid messageId: description: A UUID that persists across a single request and its corresponding callback, assigned by the CN for request messages and generated fresh by the PN for unsolicited callbacks. The CN MUST use this value to correlate incoming callbacks with the originating request and MAY use it to detect and discard duplicate messages from the PN. A new messageId MUST be generated for every new interaction. type: string format: uuid networkId: description: "The unique identifier of the Beckn subnet within which this\ \ transaction is occurring. Actors use this value to resolve the subnet's\ \ registry URL before performing identity and address lookups. The RECOMMENDED\ \ format is namespace_id followed by a slash followed by registry_id, for\ \ example acmenet.org/charge-net." type: string timestamp: description: The date and time at which this message was generated by the sender, expressed in RFC 3339 date-time format. The receiving actor MAY use this value together with ttl to assess whether the message has expired before processing. type: string format: date-time key: description: The encryption public key of the sender, provided when the sender intends for the receiver to use it for encrypting response payloads or establishing a secure channel. Assignment is by the CN or PN depending on message direction. type: string try: description: 'A boolean flag set by the CN to activate the two-phase preview pattern: when true, the PN MUST compute and return the outcome of the requested action without persisting any state change; when false (the default), the PN MUST execute and commit the action. Applicable to the `update` and `cancel` actions only. For all other actions, sending actors MUST NOT set this flag; receiving actors MUST ignore it if present.' type: boolean ttl: description: The duration, expressed in ISO 8601 duration format, after the timestamp value during which this message remains valid. The receiving actor SHOULD reject messages whose timestamp plus ttl has elapsed before processing. type: string schemaContext: description: Array of JSON-LD context urls representing the schemas relevant to the request in which this context object is transported. type: array items: type: string format: uri requestDigest: $ref: '#/components/schemas/RequestDigest' Contract: type: object description: "A domain-neutral, digitally agreed commitment between two or more\ \ participants that governs the exchange of economic or non-economic value,\ \ binding together what is promised (commitments), what value is exchanged\ \ (consideration), how execution occurs (performance), and how value is discharged\ \ (settlements).\n\nContract is the canonical transaction object across all\ \ phases of the Beckn value-exchange lifecycle from select through post-performance.\ \ The CN initially constructs the Contract in SelectAction and progressively\ \ enriches it through InitAction and ConfirmAction; the PN updates and returns\ \ it in each corresponding callback carrying the authoritative state. It is\ \ domain-neutral and supports retail, mobility, healthcare, hiring, energy\ \ markets, carbon exchanges, data access, subscriptions, and other use cases.\n\ \nRelationship: Composes Commitment, Consideration, Participant, Performance,\ \ and Settlement schemas. The status field constrains values to the Descriptor\ \ schema with code restricted to DRAFT, ACTIVE, CANCELLED, and COMPLETE. The\ \ contractAttributes field extends the core schema with domain-specific attributes\ \ via the Attributes schema." title: Contract properties: id: description: A UUID string generated at the PN endpoint at any stage before the confirmation of the order i.e before `/on_confirm` callback. This value is intended typically for indexing or filtering. While the chances of a UUID collision are rare, it is recommended to use a combination of `bppId`, `providerId` and `id` to allow for global uniqueness. type: string format: uuid descriptor: description: Describes the nature of the contract in human / agent readable terms $ref: '#/components/schemas/Descriptor' commitments: type: array description: Structured commitments governed by this contract. minItems: 1 items: $ref: '#/components/schemas/Commitment' consideration: type: array description: Value agreed to be exchanged under this contract. items: $ref: '#/components/schemas/Consideration' participants: description: 'The participants involved in the contract. Contracts are not always between two individuals. Several entities may play a specific role in the creation, performance, and post-performance of the contract.' type: array items: $ref: '#/components/schemas/Participant' performance: type: array description: "Execution units of the contract.\n\nPerformance is the generalized fulfillment abstraction.\nEach Performance instance represents a structured execution\nplan or delivery mechanism, including:\n\n - Physical delivery\n - Service provisioning\n - API access\n - Subscription activation\n - Carbon credit transfer\n - Capacity allocation\n - Workforce onboarding\n\nTracking and Support interactions may be linked to\nindividual Performance units." items: $ref: '#/components/schemas/Performance' settlements: type: array description: Records representing discharge of agreed consideration. items: $ref: '#/components/schemas/Settlement' status: description: The current state of the contract expressed as a Descriptor whose code MUST be one of the standard contract state values. allOf: - $ref: '#/components/schemas/Descriptor' - type: object properties: code: enum: - DRAFT - ACTIVE - CANCELLED - COMPLETE contractAttributes: description: Domain-specific extension attributes for this contract. allOf: - $ref: '#/components/schemas/Attributes' - {} - properties: {} additionalProperties: false required: - commitments Commitment: type: object description: "A structured record of a specific promise made within a Contract,\ \ binding together the exact resources being committed to, the offer terms\ \ under which they are being provided, and the current lifecycle status of\ \ that promise.\n\nCommitments appear from the select phase onward in the\ \ value-exchange lifecycle. The CN includes draft commitments in SelectAction\ \ referencing the resources and offers chosen from the catalog; the PN updates\ \ commitment status as the contract progresses through the DRAFT, ACTIVE, and\ \ CLOSED states.\n\nRelationship: Composes Resource schemas (with required\ \ id and quantity) in the resources array and an Offer schema (with required\ \ id and resourceIds) in the offer field. The commitmentAttributes field extends\ \ the core schema with domain-specific attributes via the Attributes schema." required: - status - resources - offer properties: id: type: string status: type: object properties: descriptor: allOf: - $ref: '#/components/schemas/Descriptor' - properties: code: enum: - DRAFT - ACTIVE - CLOSED resources: type: array items: required: - id - quantity $ref: '#/components/schemas/Resource' offer: required: - id - resourceIds $ref: '#/components/schemas/Offer' commitmentAttributes: description: Domain-specific extension attributes for this commitment. allOf: - $ref: '#/components/schemas/Attributes' - properties: {} Descriptor: $schema: https://json-schema.org/draft/2020-12/schema description: "A structured label that provides machine-readable and human-readable\ \ identification for any Beckn entity, including its code, name, descriptions,\ \ and associated media and document references.\n\nDescriptor appears throughout\ \ the value-exchange lifecycle as the standard identification and display mechanism\ \ for entities including Contract status, Resource identity, Offer metadata,\ \ Provider information, and Commitment state. Both CNs and PNs produce and\ \ consume it depending on the entity being described.\n\nRelationship: Used\ \ by composition in Contract, Resource, Offer, Provider, Commitment, Consideration,\ \ Catalog, Performance, Tracking, and Support schemas. The docs field composes\ \ Document schemas; the mediaFile field composes MediaFile schemas." title: Descriptor type: object properties: code: description: A machine-readable code identifying the state or type of the entity being described. The valid values for this field are defined by the context in which the Descriptor is used (e.g. DRAFT, ACTIVE, CANCELLED, COMPLETE for a Contract status). type: string longDesc: description: Detailed description of the item type: string example: Powerful gaming laptop with NVIDIA RTX graphics, fast SSD storage, and high-refresh display shortDesc: description: Short description of the item type: string example: High-performance gaming laptop with RTX graphics name: description: Name of the entity being described type: string example: Premium Gaming Laptop Pro thumbnailImage: description: Name of the entity being described type: string format: uri docs: description: Links to downloadable business/supporting documents type: array items: $ref: '#/components/schemas/Document' mediaFile: description: Links to multimedia files and images type: array items: $ref: '#/components/schemas/MediaFile' additionalProperties: false Document: description: "A downloadable or displayable document artifact associated with\ \ a Beckn entity, such as a terms and conditions PDF, a verifiable credential,\ \ or a signed contract document, distinguished from media files by its support\ \ for cryptographic signature and schema metadata.\n\nDocuments appear wherever\ \ a Beckn entity requires supporting documentary evidence across the value-exchange\ \ lifecycle, including offer terms, contract documents, and post-performance\ \ receipts. Both CNs and PNs produce and consume them via the Descriptor.docs\ \ field.\n\nRelationship: Used by composition within the Descriptor schema\ \ via the docs array. Intentionally kept separate from MediaFile to accommodate\ \ signature, checksum, and schema metadata fields not applicable to media assets." title: Document x-tags: - common type: object properties: label: description: The display name of the media file type: string mimeType: description: MIME type if 'data' is provided (application/pdf, image/png, application/json). type: string standard: description: Describes the schema type in case the document follows a standard schema like a verifiableCredential type: string url: description: URL to the document type: string format: uri security: type: object properties: checksum: type: string checksumAlgorithm: type: string enum: - SHA256 - SHA512 - OTHER signature: type: string signatureAlgorithm: type: string description: e.g., Ed25519, ES256 keyId: type: string required: - label - url - mimeType additionalProperties: false Error: title: Error description: "A canonical Beckn error returned in NACK responses and asynchronous\ \ error callbacks. The topmost (Level 1) Error in any payload MUST carry a\ \ code from the canonical Beckn error code enum. The self-referencing details.cause\ \ property (Level 2) MAY carry domain-specific or non-canonical error codes\ \ from downstream systems, enabling typed error chains across protocol stack\ \ layers and network hops.\n\nError appears in NackBadRequest (400), NackUnauthorized\ \ (401), AckNoCallback (202), and AsyncError across all phases of the value-exchange\ \ lifecycle. Both PNs and CNs produce errors depending on the direction of\ \ the failing call; the counterpart consumes them to determine corrective action.\n\ \nRelationship: Extended by the AsyncError schema. Composed within the NackBadRequest,\ \ NackUnauthorized, AckNoCallback, and ServerError schemas." type: object required: - code - message properties: code: type: string description: "Canonical error code. MUST be a value from the ErrorCode\ \ enum schema. The prefix indicates the protocol stack layer at which\ \ the error originated: CTX_ (context/routing), NET_ (networking), AUT_\ \ (authentication/trust), SCH_ (core/linked data schema), POL_ (policy),\ \ BIZ_ (application/business logic), DOM_ (domain-specific)." example: SCH_FIELD_NOT_ALLOWED message: type: string description: Human-readable description of the error. example: "Field 'electronic:invalidField' not found in ElectronicItem schema" details: type: object description: "Additional structured error details. The well-known key 'path'\ \ identifies the failing field. The 'cause' key carries the underlying\ \ root-cause Error (self-referencing), enabling typed error chains across\ \ protocol stack layers and network hops." properties: path: type: string description: JSONPath expression or field reference that failed validation. example: "$.message.order.items[0].quantity.count" cause: description: "Optional Level 2 Error representing the underlying root\ \ cause, such as a downstream provider error, registry failure, or\ \ domain-specific error (OCPI, FHIR, OCPP). MAY carry non-canonical\ \ codes." $ref: '#/components/schemas/Error' additionalProperties: false additionalProperties: false FormSubmission: title: FormSubmission x-tags: - common description: "A consumer's submitted response to a structured feedback form,\ \ capturing the filled-in field values keyed by form field identifiers as\ \ defined in the form schema.\n\nFormSubmission appears in the post-performance\ \ phase of the value-exchange lifecycle. The CN produces it as part of a\ \ RatingInput when the consumer has completed a structured feedback form returned\ \ by the PN in a prior on_rate preview response; the PN consumes it to record\ \ structured qualitative feedback alongside the numeric rating.\n\nRelationship:\ \ Composed within the RatingInput schema via the feedbackFormSubmission field." type: object properties: id: description: Identifier of the form that was submitted. Typically the form's URL or the value of the form's url field. type: string format: uri submissionId: description: Unique identifier for this form submission instance. type: string format: uuid data: description: Key-value map of form field names to submitted values. Keys correspond to the field identifiers defined in the form; values are the user's responses as strings. type: object additionalProperties: type: string submittedAt: description: Timestamp at which the form was submitted, in RFC 3339 / ISO 8601 format. type: string format: date-time required: - data additionalProperties: false Participant: type: object description: "An identified party that plays a specific role in the creation,\ \ performance, or post-performance of a Contract, which may represent a consumer,\ \ provider, agent, or any other actor bound by the contract's terms.\n\nParticipants\ \ appear in the negotiation and performance phases of the value-exchange lifecycle.\ \ The CN introduces consumer participant details in InitAction; the PN may\ \ add provider or agent participant records in the corresponding callback.\ \ Both actors consume participant records to understand the parties bound by\ \ the contract.\n\nRelationship: Composed within the Contract schema's participants\ \ array. The participantAttributes field extends the core schema with domain-specific\ \ actor attributes via the Attributes schema." properties: id: type: string descriptor: $ref: '#/components/schemas/Descriptor' participantAttributes: description: 'Domain-specific extension attributes for this participant.' $ref: '#/components/schemas/Attributes' GeoJSONGeometry: description: "A GeoJSON geometry object per RFC 7946, representing the spatial\ \ shape of a geographic feature such as a point location, a route, a service\ \ area polygon, or a collection of geometric shapes.\n\nGeoJSONGeometry appears\ \ wherever spatial coordinates are needed in the value-exchange lifecycle,\ \ including provider and resource locations in Catalog, delivery locations\ \ in Performance, and spatial constraint reference geometries in SpatialConstraint\ \ within DiscoverAction. Both CNs and PNs produce and consume it depending\ \ on context.\n\nCoordinates MUST be in EPSG:4326 (WGS-84) and MUST follow\ \ longitude, latitude, optional altitude order as specified in RFC 7946. Supported\ \ geometry types are Point, LineString, Polygon, MultiPoint, MultiLineString,\ \ MultiPolygon, and GeometryCollection. For circular search areas, callers\ \ MUST use SpatialConstraint with op S_DWITHIN and a Point plus distanceMeters\ \ rather than attempting to express a circle as a geometry type.\n\nRelationship:\ \ Used by composition within the Location schema for geographic positioning\ \ and within SpatialConstraint as the reference geometry for spatial predicates." title: GeoJSONGeometry type: object properties: bbox: description: Optional bounding box `[west, south, east, north]` in degrees. type: array minItems: 4 maxItems: 4 items: type: number coordinates: description: Coordinates per RFC 7946 for all types **except** GeometryCollection. Order is **[lon, lat, (alt)]**. For Polygons, this is an array of linear rings; each ring is an array of positions. type: array items: {} geometries: description: Member geometries when `type` is **GeometryCollection**. type: array items: $ref: '#/components/schemas/GeoJSONGeometry' type: type: string enum: - Point - LineString - Polygon - MultiPoint - MultiLineString - MultiPolygon - GeometryCollection required: - type additionalProperties: true Performance: description: "A domain-neutral execution unit within a Contract that describes\ \ how a specific commitment will be fulfilled, including when and where delivery\ \ or service provisioning occurs, the current execution status, and linkage\ \ to tracking and support interactions.\n\nPerformance appears in the fulfillment\ \ phase of the value-exchange lifecycle, introduced by the PN in OnConfirmAction\ \ and updated in OnStatusAction and OnUpdateAction callbacks. The CN consumes\ \ performance records to present fulfillment progress to the consumer; the\ \ PN updates them as execution proceeds.\n\nPerformance is domain-neutral\ \ and can represent physical delivery, service provisioning, API access activation,\ \ subscription activation, carbon credit transfer, capacity allocation, or\ \ workforce onboarding. Domain-specific delivery details MUST be placed inside\ \ performanceAttributes using a well-known domain schema such as HyperlocalDelivery\ \ for hyperlocal physical delivery, or the generic Attributes schema when no\ \ well-known domain schema exists.\n\nRelationship: Composed within the Contract\ \ schema's performance array. The performanceAttributes field extends the core\ \ schema with domain-specific fulfillment details via the Attributes schema.\ \ The commitmentIds field references one or more Commitment identifiers that\ \ this performance unit satisfies." title: Fulfillment x-tags: - common - fulfillment type: object properties: id: type: string description: Unique identifier for this fulfillment record. status: $ref: '#/components/schemas/Descriptor' description: Current status of this fulfillment, expressed as a Descriptor. Use Descriptor.code for machine-readable status values. commitmentIds: type: array items: $ref: '#/components/schemas/Commitment/properties/id' performanceAttributes: description: Domain-specific extension attributes for this fulfillment. Use beckn:HyperlocalDelivery (aligned with schema:ParcelDelivery) for hyperlocal physical delivery. Use the generic Attributes schema for other fulfillment types where no well-known domain schema exists. $ref: '#/components/schemas/Attributes' additionalProperties: false RequestDigest: title: Request Payload Digest description: "A cryptographic binding that ties an asynchronous callback to\ \ the specific inbound request that triggered it, establishing bilateral non-repudiation\ \ for the asynchronous leg of a Beckn interaction.\n\nRequestDigest appears\ \ in the Context of callback requests across all phases of the value-exchange\ \ lifecycle. The implementing actor (PN or CN) produces it by hashing the\ \ original inbound request body and including that hash in the callback Context;\ \ the receiving actor verifies it to confirm that the callback corresponds\ \ to the claimed original request.\n\nVerification requires two steps: recomputing\ \ the BLAKE2b-512 digest of the original request body and comparing it to\ \ the digest field, then confirming that the messageId matches the messageId\ \ from the original request Context.\n\nRelationship: Composed within the\ \ Context schema via the requestDigest property." type: object required: - digest properties: digest: type: string pattern: ^BLAKE-512=[A-Za-z0-9+/]+=*$ description: 'BLAKE2b-512 hash of the parent request body, Base64-encoded with algorithm prefix. Format: `BLAKE-512={base64EncodedHash}`' Intent: description: "A structured expression of a consumer's desire to discover resources,\ \ services, or providers matching specific criteria, combining free-text search,\ \ structured filter expressions, spatial constraints, and media-based search\ \ inputs.\n\nIntent appears exclusively at the start of the value-exchange\ \ lifecycle, within DiscoverAction. The CN constructs it based on the consumer's\ \ search inputs; the DS (Discovery Service) evaluates it against its indexed\ \ catalog store to identify matching resources and offers.\n\nFabric context:\ \ The Intent is applied against the DS's indexed catalog store.\n\nRelationship:\ \ Composed within the DiscoverAction schema as the required intent property.\ \ The spatial field composes one or more SpatialConstraint schemas; the mediaSearch\ \ field composes the MediaSearch schema." title: Intent type: object properties: textSearch: description: Free text search query for items type: string example: gaming laptop premium tech filters: description: Filter criteria for items type: object properties: type: description: Type of filter expression type: string enum: - jsonpath default: jsonpath expression: description: Filter expression based on the specified type type: string example: $[?(@.rating.value >= 4.0 && @.electronic.brand.name == 'Premium Tech')] required: - type - expression spatial: description: Optional array of spatial constraints (CQL2-JSON semantics). type: array items: $ref: '#/components/schemas/SpatialConstraint' mediaSearch: $ref: '#/components/schemas/MediaSearch' additionalProperties: false Location: description: "A geographic place combining a precise GeoJSON geometry with an\ \ optional human-readable postal address, used to express physical positions,\ \ service areas, delivery points, and provider operating locations.\n\nLocation\ \ appears throughout the value-exchange lifecycle wherever a physical place\ \ must be specified, including provider operating locations in Catalog, delivery\ \ and pickup points in Performance, and spatial constraint reference points\ \ in SpatialConstraint. Both CNs and PNs produce and consume it.\n\nRelationship:\ \ Composes the GeoJSONGeometry schema in the required geo field and the Address\ \ schema in the optional address field. Geometry is the authoritative spatial\ \ representation; Address is the human-readable supplement." type: object required: - geo additionalProperties: false properties: geo: $ref: '#/components/schemas/GeoJSONGeometry' address: $ref: '#/components/schemas/Address' MediaFile: description: "A visual or audio-visual asset associated with a Beckn entity,\ \ such as a product image, promotional video, or audio description, intended\ \ primarily for display or playback within a consumer-facing application.\n\ \nMediaFile appears wherever a Beckn entity requires associated visual or\ \ multimedia presentation across the value-exchange lifecycle, including resource\ \ images in Catalog and offer illustration assets. Both CNs and PNs produce\ \ and consume them via the Descriptor.mediaFile field.\n\nRelationship: Used\ \ by composition within the Descriptor schema via the mediaFile array. Intentionally\ \ kept separate from Document, which supports cryptographic metadata such as\ \ signatures and checksums not applicable to media assets." title: MediaFile x-tags: - common type: object properties: label: description: The display name of the media file type: string mimeType: description: MIME type if 'data' is provided (application/pdf, image/png). type: string example: image/png uri: description: URL to the document type: string format: uri additionalProperties: false MediaInput: type: object description: "A single media asset submitted by the CN as part of a media-based\ \ discovery query, enabling the DS (Discovery Service) to find catalog items\ \ that are visually similar to, semantically related to, or described by the\ \ provided image, audio, or video.\n\nMediaInput appears exclusively within\ \ the DiscoverAction during the discovery phase of the value-exchange lifecycle.\ \ The CN constructs it based on the consumer's media input; the DS uses it\ \ as a search signal alongside textual and spatial constraints.\n\nRelationship:\ \ Composed within the MediaSearch schema's media array, which is itself composed\ \ within the Intent schema." required: - type - url properties: id: type: string type: type: string enum: - image - audio - video url: type: string format: uri contentType: type: string textHint: type: string language: type: string startMs: type: integer endMs: type: integer additionalProperties: false MediaSearch: type: object description: "A container grouping one or more media assets and associated search\ \ options that the CN submits as part of a media-based discovery query, allowing\ \ the DS (Discovery Service) to perform similarity or content-extraction searches\ \ across indexed catalog items.\n\nMediaSearch appears exclusively within\ \ the Intent schema during the discovery phase of the value-exchange lifecycle.\ \ The CN constructs it when the consumer initiates a discovery using a visual\ \ or audio reference rather than text.\n\nRelationship: Composed within the\ \ Intent schema via the mediaSearch field. Composes MediaInput schemas in the\ \ media array and MediaSearchOptions in the options field." properties: media: type: array items: $ref: '#/components/schemas/MediaInput' options: $ref: '#/components/schemas/MediaSearchOptions' additionalProperties: false MediaSearchOptions: type: object description: "Configuration options that govern how the DS (Discovery Service)\ \ interprets and processes the media assets supplied in a MediaSearch, specifying\ \ the search goals and whether media signals should be combined with text search\ \ or used as the sole relevance criterion.\n\nMediaSearchOptions appears exclusively\ \ within the MediaSearch schema during the discovery phase of the value-exchange\ \ lifecycle. The CN sets these options based on the consumer's search intent;\ \ the DS applies them when evaluating media inputs against indexed catalog\ \ items.\n\nRelationship: Composed within the MediaSearch schema via the options\ \ field." properties: goals: type: array items: type: string enum: - visual-similarity - visual-object-detect - text-from-image - text-from-audio - semantic-audio-match - semantic-video-match augment_text_search: type: boolean default: true restrict_results_to_media_proximity: type: boolean default: false additionalProperties: false Offer: type: object description: "A domain-neutral, cross-domain structure that captures the commercial\ \ or transactional terms under which one or more Resources may be committed\ \ within a Contract, including eligibility conditions, pricing, add-ons, and\ \ validity constraints.\n\nOffers appear in the discovery and negotiation phases\ \ of the value-exchange lifecycle. The PN produces them as part of a Catalog\ \ to describe how resources may be transacted; the CN references offer identifiers\ \ when constructing Commitments in SelectAction, and the PN returns updated\ \ offers with confirmed considerations in subsequent callbacks.\n\nRelationship:\ \ Composed within Catalog, Commitment, and AddOn schemas. Composes Provider,\ \ Consideration, and Attributes schemas. The resourceIds field references Resource\ \ identifiers covered by the offer. The addOns field composes AddOn schemas\ \ for optional supplementary items." required: - id properties: id: type: string description: Unique identifier of the offer. descriptor: description: Human / agent-readable description of this offer. $ref: '#/components/schemas/Descriptor' provider: $ref: '#/components/schemas/Provider' resourceIds: type: array description: References (IDs) to resources covered by this offer. items: $ref: '#/components/schemas/Resource/properties/id' addOns: type: array description: A list of add-ons that may be included with this offer. items: $ref: '#/components/schemas/AddOn' considerations: type: array description: Proposed value to be exchanged under this offer, e.g. Price for a retail item items: $ref: '#/components/schemas/Consideration' validity: $ref: '#/components/schemas/TimePeriod' offerAttributes: $ref: '#/components/schemas/Attributes' Provider: type: object description: "A registered entity on the Beckn network that makes resources\ \ and offers available through one or more catalogs, operating from one or\ \ more physical or virtual locations.\n\nProviders appear in the discovery\ \ phase of the value-exchange lifecycle as part of a Catalog, and persist\ \ through the negotiation phase as the counterparty identified in Offers. The\ \ PN produces provider records; the CN consumes them to identify and display\ \ the source of the resources and offers being considered.\n\nRelationship:\ \ Composed within the Catalog and Offer schemas. The availableAt field composes\ \ one or more Location schemas representing the provider's physical operating\ \ sites. The providerAttributes field extends the core schema with domain-specific\ \ attributes via the Attributes schema." title: Provider properties: id: description: Unique identifier for the provider type: string example: tech-store-001 descriptor: $ref: '#/components/schemas/Descriptor' availableAt: description: Physical locations where the provider operates type: array items: $ref: '#/components/schemas/Location' providerAttributes: $ref: '#/components/schemas/Attributes' required: - id - descriptor additionalProperties: false RatingInput: $schema: https://json-schema.org/draft/2020-12/schema description: "A structured rating record that captures a consumer's numeric\ \ assessment and optional qualitative feedback for a specific entity associated\ \ with a completed contract, including the contract itself, individual resources,\ \ fulfillment stages, providers, agents, or support interactions.\n\nRatingInput\ \ appears in the post-performance phase of the value-exchange lifecycle, within\ \ RateAction (produced by the CN) and OnRateAction (produced by the PN).\ \ The CN submits rating inputs to record consumer feedback; the PN may also\ \ return rating form definitions as RatingInput structures in preview mode\ \ to guide the consumer's rating submission.\n\nRelationship: Composed within\ \ the RateAction.ratingInputs and OnRateAction.ratings arrays. The feedbackFormSubmission\ \ field composes a FormSubmission schema to carry structured qualitative feedback\ \ alongside the numeric rating." title: RatingInput x-tags: - common type: object properties: target: description: The thing being rated. It could be a person, an application, a service, a product, an instrument used in the fulfillment of the contract, or the overall experience. type: object properties: id: description: ID of the entity being rated (order/item/fulfillment/provider/agent). type: string descriptor: $ref: '#/components/schemas/Descriptor' targetAttributes: $ref: '#/components/schemas/Attributes' range: type: object feedbackFormSubmission: description: The submission to the feedback form sent along with a rating request $ref: '#/components/schemas/FormSubmission' required: - target - range additionalProperties: false Resource: type: object description: "A domain-neutral, referenceable unit of value, capability, service,\ \ entitlement, or asset that a provider makes available on the network and\ \ that a consumer may select and commit to within a Contract.\n\nResources\ \ appear across all phases of the value-exchange lifecycle. The PN defines\ \ them in a Catalog during the discovery phase; the CN references them in\ \ Commitments during the selection phase; and the PN confirms their provisioning\ \ in the performance array during fulfillment. Examples include a retail product\ \ SKU, a mobility ride, a job role, a carbon credit unit, a dataset or API\ \ entitlement, a training course slot, and a clinic appointment.\n\nRelationship:\ \ Composed within Catalog, Commitment, and AddOn schemas. The resourceAttributes\ \ field extends the core schema with domain-specific resource characteristics\ \ via the Attributes schema, enabling domain packs to attach structured fields\ \ without modifying the core schema." required: - id properties: id: type: string description: Globally unique identifier of the resource. descriptor: $ref: '#/components/schemas/Descriptor' resourceAttributes: description: All the properties of a resource that describe its value, its terms of usage, fulfillment, and consideration $ref: '#/components/schemas/Attributes' Settlement: type: object description: "A record representing the discharge of an agreed consideration\ \ within a Contract, tracking the progression from a draft payment intent\ \ through a committed payment instruction to a completed settlement.\n\nSettlements\ \ appear across the negotiation and performance phases of the value-exchange\ \ lifecycle. The CN introduces draft settlement records in ConfirmAction to\ \ carry payment proof or reference; the PN updates settlement status through\ \ COMMITTED and COMPLETE as payment is processed and discharged.\n\nRelationship:\ \ Composed within the Contract schema's settlements array. The considerationId\ \ field references a Consideration identifier within the same Contract, linking\ \ the settlement to the specific value obligation being discharged. The settlementAttributes\ \ field extends the core schema with domain-specific payment details via the\ \ Attributes schema." properties: id: type: string considerationId: $ref: '#/components/schemas/Consideration/properties/id' status: type: string enum: - DRAFT - COMMITTED - COMPLETE settlementAttributes: $ref: '#/components/schemas/Attributes' Signature: title: Beckn HTTP Signature description: "A digitally signed authentication credential transmitted in the\ \ HTTP Authorization header of CN requests and PN-initiated callbacks,\ \ proving the identity of the sending network participant and ensuring the\ \ integrity of the request body.\n\nThe sending actor produces this by signing\ \ a three-line canonical signing string with its Ed25519 private key registered\ \ on the fabric GRR:\n\n (created): {unix_timestamp}\n (expires): {unix_timestamp}\n\ \ digest: BLAKE2b-512={base64_body_hash}\n\nThe `headers` attribute of\ \ the Authorization header MUST be `\"(created) (expires) digest\"`. The\ \ `keyId` field identifies the signer using the format `{namespace}/{registry}/{record}|ed25519`\ \ (implicit, resolved at GRR) or a full dedi protocol URL followed by `|ed25519`\ \ (explicit). The algorithm MUST be `ed25519`. The body digest MUST use BLAKE2b-512\ \ encoded as `BLAKE2b-512={Base64}`.\n\nUsed for: CN→PN requests across\ \ all phases of the value-exchange lifecycle; PN→CN PN-initiated callbacks.\ \ The receiving actor verifies it against the sender's registered public key.\ \ Requests with an absent, expired, or unverifiable Signature MUST be rejected\ \ with 401 NackUnauthorized.\n\nFor PN solicited callbacks, use CallbackSignature\ \ instead. For synchronous response signing, see components/headers/AckSignatureHeader.\ \ See NFH-004 Authentication and Trust for the full specification." type: string pattern: ^Signature keyId="[^"]+",algorithm="ed25519",created="\d+",expires="\d+",headers="\(created\) \(expires\) digest",signature="[A-Za-z0-9+/]+=*"$ example: 'Signature keyId="example.ns/gro.example/bap-key-001|ed25519",algorithm="ed25519",created="1714000000",expires="1714000600",headers="(created) (expires) digest",signature="BASE64SIGNATURE=="' CallbackSignature: title: Beckn HTTP Callback Signature description: "A digitally signed authentication credential transmitted in the\ \ HTTP Authorization header of PN solicited callbacks to CN `/on_*` endpoints.\ \ Extends the standard Signature by chaining the PN's signature to the CN's\ \ original request signature, allowing the CN to verify that the callback\ \ is a genuine response to a request it sent.\n\nThe PN produces this by\ \ signing a four-line canonical signing string with its Ed25519 private key:\n\ \n (created): {unix_timestamp}\n (expires): {unix_timestamp}\n digest:\ \ BLAKE2b-512={base64_callback_body_hash}\n request-signature: {cn_raw_base64_signature}\n\ \nThe fourth line (`request-signature`) contains the raw Base64 Ed25519 signature\ \ value extracted verbatim from the `signature=\"...\"` field of the CN's\ \ original `Authorization` header. This binds the callback cryptographically\ \ to the triggering request.\n\nThe `headers` attribute MUST be `\"(created)\ \ (expires) digest request-signature\"`. The `keyId` identifies the PN signer.\ \ The algorithm MUST be `ed25519`. The body digest covers the callback body\ \ using BLAKE2b-512.\n\nUsed for: PN→CN solicited callbacks only. For PN-initiated\ \ notifications (no preceding CN request), use the standard Signature schema\ \ instead. For synchronous response signing, see components/headers/AckSignatureHeader.\ \ See NFH-004 Authentication and Trust §6 for the full callback signing procedure." type: string pattern: ^Signature keyId="[^"]+",algorithm="ed25519",created="\d+",expires="\d+",headers="\(created\) \(expires\) digest request-signature",signature="[A-Za-z0-9+/]+=*"$ example: 'Signature keyId="example.ns/gro.example/bpp-key-001|ed25519",algorithm="ed25519",created="1714000060",expires="1714000660",headers="(created) (expires) digest request-signature",signature="BPPSIGNATURE=="' AckSignature: title: Beckn HTTP Ack Signature description: "A digitally signed authentication credential transmitted in the\ \ HTTP `Signature` response header on every synchronous Beckn response, proving\ \ that the responding NP received and authenticated the specific inbound request.\n\ \nThe responding actor produces this by signing a four-line canonical signing\ \ string with its Ed25519 private key:\n\n (created): {unix_timestamp}\n\ \ (expires): {unix_timestamp}\n digest: BLAKE2b-512={base64_response_body_hash}\n\ \ request-signature: {incoming_request_raw_base64_signature}\n\nThe fourth\ \ line (`request-signature`) contains the raw Base64 Ed25519 signature value\ \ extracted verbatim from the `signature=\"...\"` field of the incoming request's\ \ `Authorization` header. This binds the Ack cryptographically to the specific\ \ signed request that triggered it.\n\nThe `headers` attribute MUST be `\"(created)\ \ (expires) digest request-signature\"`. The `keyId` identifies the responding\ \ NP. The algorithm MUST be `ed25519`. The body digest covers the response\ \ body using BLAKE2b-512.\n\nUsed for: all synchronous HTTP responses across\ \ all Beckn endpoints. For request signing, see Signature. For PN solicited\ \ callback signing, see CallbackSignature. See NFH-004 Authentication and\ \ Trust §5 for the full response signing procedure." type: string pattern: ^Signature keyId="[^"]+",algorithm="ed25519",created="\d+",expires="\d+",headers="\(created\) \(expires\) digest request-signature",signature="[A-Za-z0-9+/]+=*"$ example: 'Signature keyId="example.ns/gro.example/bpp-key-001|ed25519",algorithm="ed25519",created="1714000060",expires="1714000660",headers="(created) (expires) digest request-signature",signature="ACKSIGNATURE=="' Support: description: "A structured record representing a consumer's request for assistance\ \ related to an entity associated with a contract, carrying the entity reference,\ \ a description of the support need, and the available or assigned support\ \ channels.\n\nSupport appears in the post-performance phase of the value-exchange\ \ lifecycle, within SupportAction (produced by the CN) and OnSupportAction\ \ (produced by the PN). The CN constructs it to describe the nature and\ \ target of the support request; the PN returns it with populated channel\ \ details and, when a ticket has been created, the ticket reference.\n\nRelationship:\ \ Composed within the SupportAction and OnSupportAction schemas as the primary\ \ carrier. The channels field composes Attributes schemas to express domain-specific\ \ channel details such as phone, email, or chat endpoints." title: Support type: object properties: orderId: description: The order against which support is required type: string descriptor: description: A description of the nature of support needed $ref: '#/components/schemas/Descriptor' channels: description: Available support channels described in individual linked data JSON objects type: array minItems: 1 items: $ref: '#/components/schemas/Attributes' additionalProperties: false SpatialConstraint: description: "An OGC CQL2 spatial predicate applied to one or more geometry\ \ fields within catalog items, expressing the spatial intent of a discovery\ \ request such as finding resources within a geographic area, along a route,\ \ or within a distance of a reference point.\n\nSpatialConstraint appears\ \ exclusively within the Intent schema during the discovery phase of the value-exchange\ \ lifecycle. The CN constructs it to express the consumer's geographic search\ \ criteria; the DS (Discovery Service) applies it as a spatial filter against\ \ catalog items' geometry fields.\n\nThe op field MUST be one of the standard\ \ OGC CQL2 spatial operators: S_WITHIN (catalog geometry is completely inside\ \ the constraint geometry), S_INTERSECTS (geometries overlap), S_CONTAINS\ \ (catalog geometry contains the constraint geometry), S_DISJOINT (geometries\ \ do not overlap), S_OVERLAPS, S_CROSSES, S_TOUCHES, S_EQUALS, or S_DWITHIN\ \ (catalog geometry is within distanceMeters of the constraint geometry). The\ \ distanceMeters field is required when op is S_DWITHIN. All coordinates MUST\ \ be in EPSG:4326 unless overridden by the srid field.\n\nRelationship: Composed\ \ within the Intent schema's spatial array. Composes the GeoJSONGeometry schema\ \ in the geometry field as the reference geometry for the spatial predicate." title: SpatialConstraint type: object properties: op: description: OGC CQL2 spatial operator. type: string enum: - S_WITHIN - S_CONTAINS - S_INTERSECTS - S_DISJOINT - S_OVERLAPS - S_CROSSES - S_TOUCHES - S_EQUALS - S_DWITHIN targets: description: '''One or more JSONPath-like pointers to geometry fields within the item. Example pointers: - `$[''''availableAt''''][*][''''geo'''']` (array of site Points) - `$[''''itemAttributes''''][''''ride:dropOff''''][''''geo'''']` (drop zone Polygon)'' ' oneOf: - type: string - type: array items: type: string geometry: $ref: '#/components/schemas/GeoJSONGeometry' distanceMeters: description: 'For `S_DWITHIN`: maximum distance in meters from the target geometry to `geometry` (e.g., "within 5000 m of this Point"). Ignored for other ops.' type: number minimum: 0 quantifier: description: '''How to evaluate when `targets` resolves to an array - - **any**: at least one element matches (default) - **all**: every element must match - **none**: no element may match'' ' type: string enum: - ANY - ALL - NONE default: any srid: description: Coordinate Reference System identifier for `geometry`. Default is `"EPSG:4326"`. If provided, servers MAY reproject to EPSG:4326 internally. type: string example: EPSG:4326 required: - op - targets additionalProperties: false x-tags: - common TimePeriod: description: "A temporal window defined by start and end boundaries that constrains\ \ the period during which a catalog, offer, or resource is valid and available\ \ for discovery and commitment.\n\nTimePeriod appears in the discovery and\ \ negotiation phases of the value-exchange lifecycle, within Catalog.validity\ \ and Offer.validity. The PN assigns validity windows to catalog and offer\ \ entries; the CN consumes them to determine whether a catalog or offer is\ \ currently available. At least one of startDate, endDate, or a startTime\ \ and endTime pair MUST be provided.\n\nRelationship: Used by composition\ \ within the Catalog and Offer schemas via the validity field." title: TimePeriod x-tags: - common type: object properties: startDate: description: Start instant (inclusive) type: string format: date-time endDate: description: End instant in RFC 3339 date-time format type: string format: date-time example: '2025-12-31T23:59:59Z' startTime: description: Start time of the time period type: string format: time endTime: description: End time of the time period type: string format: time anyOf: - required: - startDate - required: - endDate - required: - startTime - endTime additionalProperties: false Tracking: description: "A handle that provides the CN with the URL or WebSocket endpoint\ \ needed to subscribe to real-time position and progress updates for an active\ \ fulfillment stage of a confirmed contract.\n\nTracking appears in the fulfillment\ \ phase of the value-exchange lifecycle, within TrackAction (produced by the\ \ CN) and OnTrackAction (produced by the PN). The PN produces it when a\ \ /track request is received, supplying the live data stream endpoint and\ \ indicating whether tracking is currently active or inactive; the CN consumes\ \ it to connect to the real-time data stream.\n\nRelationship: Composed within\ \ the TrackAction and OnTrackAction schemas as the primary carrier. The contract\ \ field composes the Contract schema (with a required id) to identify the\ \ contract being tracked. The trackingAttributes field extends the core schema\ \ with domain-specific tracking metadata via the Attributes schema." title: Tracking type: object properties: contract: description: Attributes of the contract for which the tracking is performed allOf: - $ref: "#/components/schemas/Contract" - required: - id status: type: string enum: - ACTIVE - INACTIVE url: description: Link/handle to off-network tracking UI or endpoint. type: string format: uri trackingAttributes: description: Information specific to the use case for which the tracking is performed $ref: "#/components/schemas/Attributes" required: - url - status Ack: description: "The synchronous acknowledgement body returned by the implementing\ \ actor (PN or CN) for every accepted Beckn request, carrying the processing\ \ status and a messageId of the received request.\n\nAck appears\ \ as the response body for every 200 response across all phases of the value-exchange\ \ lifecycle. The implementing actor also signs the response digest and returns \ \ the signature of the response payload in the response header synchronously \ \ upon accepting a request; the calling actor verifies the signature to confirm that \ \ its request was authenticated and accepted for asynchronous processing.\n\ \nRelationship: Extended by the AckNoCallback and NackBadRequest schemas for\ \ specific response conditions." type: object required: - message properties: message: type: object required: - status - messageId properties: status: type: string enum: - ACK - NACK description: ACK if the request was accepted; NACK if rejected. messageId: description: The message id of the request sent in the context, to which this acknowledgement is being returned. type: string format: uuid error: $ref: '#/components/schemas/Error' AckNoCallback: description: "The synchronous response body returned when the implementing actor\ \ has authenticated and received the request but has determined that no asynchronous\ \ callback will follow, for example because no matching catalog was found,\ \ inventory is unavailable, or the provider is closed.\n\nAckNoCallback appears as\ \ the response body for 202 responses across all phases of the value-exchange\ \ lifecycle where the endpoint supports this response code. The implementing\ \ actor (PN, DS, or CS) produces it; the calling actor (CN or PN) consumes\ \ the error field to understand why no callback will follow and to decide\ \ whether to modify and resubmit the request.\n\nRelationship: Extends the\ \ Ack schema, inheriting status and signature fields and adding a required\ \ error field composed of an Error schema explaining why no callback will be\ \ sent." type: object required: - message properties: message: type: object required: - status - messageId - error properties: status: type: string enum: - ACK - NACK description: ACK if the request was accepted; NACK if rejected. messageId: type: string format: uuid error: $ref: '#/components/schemas/Error' NackBadRequest: description: "The synchronous rejection body returned when the request body\ \ is structurally invalid, missing required fields, or carries a value that\ \ fails semantic validation, indicating that the implementing actor has not\ \ processed the request.\n\nNackBadRequest appears as the response body for\ \ 400 responses across all phases of the value-exchange lifecycle. The implementing\ \ actor (PN, CN, or Fabric service) produces it; the calling actor MUST\ \ correct the request before retrying.\n\nRelationship: Extends the Ack schema\ \ with status constrained to NACK and adds an error field composed of an Error\ \ schema describing the validation failure." type: object required: - message properties: message: type: object required: - status - messageId - error properties: status: type: string const: NACK messageId: type: string format: uuid error: $ref: '#/components/schemas/Error' NackUnauthorized: description: "The synchronous rejection body returned when the Beckn HTTP Signature\ \ on the request is absent, expired, or fails verification against the sender's\ \ public key returned by the subnet registry lookup, indicating that the implementing\ \ actor has not authenticated or processed the request.\n\nNackUnauthorized\ \ appears as the response body for 401 responses across all phases of the\ \ value-exchange lifecycle. The implementing actor (PN, CN, or Fabric service)\ \ produces it; the calling actor MUST correct its signing credential or key\ \ registration before retrying.\n\nRelationship: Extends the Ack schema with\ \ status constrained to NACK and adds an error field composed of an Error\ \ schema describing the authentication failure." type: object required: - message properties: message: type: object required: - status - messageId - error properties: status: type: string const: NACK messageId: type: string format: uuid error: $ref: '#/components/schemas/Error' ServerError: description: "The response body returned when an unexpected internal failure\ \ on the implementing actor's application prevented the request from being\ \ processed, indicating a transient server-side error rather than a client-side\ \ fault.\n\nServerError appears as the response body for 500 responses across\ \ all phases of the value-exchange lifecycle. The implementing actor produces\ \ it; the calling actor SHOULD treat it as a transient error and MAY retry\ \ the request after a suitable backoff interval.\n\nRelationship: Composes\ \ the optional Error schema via the error field to carry additional diagnostic\ \ detail when available." type: object required: - message properties: message: type: object required: - status - messageId properties: status: type: string const: NACK messageId: type: string format: uuid error: $ref: '#/components/schemas/Error' ErrorCode: title: ErrorCode description: "Canonical Beckn Protocol v2 error code enum. The prefix indicates\ \ the protocol stack layer at which the error originated. Error.code MUST\ \ be one of these values. Defined by NFH-008 (Handling Exceptions and Errors)." type: string enum: - CTX_MISSING_FIELD - CTX_INVALID_FIELD - CTX_ACTION_MISMATCH - CTX_VERSION_UNSUPPORTED - CTX_TTL_EXPIRED - CTX_MESSAGE_ID_DUPLICATE - CTX_TRANSACTION_ID_UNKNOWN - CTX_CALLBACK_URL_MISSING - CTX_INVALID_BPP_URI - AUT_SIGNATURE_MISSING - AUT_SIGNATURE_INVALID - AUT_SUBSCRIBER_NOT_FOUND - AUT_KEY_NOT_FOUND - AUT_KEY_EXPIRED_OR_REVOKED - AUT_UNAUTHORIZED_ACTION - AUT_DOMAIN_NOT_ALLOWED - AUT_REPLAY_DETECTED - AUT_RATE_LIMITED - SCH_INVALID_JSON - SCH_SCHEMA_VALIDATION_FAILED - SCH_REQUIRED_FIELD_MISSING - SCH_FIELD_NOT_ALLOWED - SCH_INVALID_ENUM - SCH_INVALID_FORMAT - SCH_INVALID_JSONPATH - SCH_INVALID_JSONLD_CONTEXT - SCH_TYPE_NOT_SUPPORTED - SCH_ATTRIBUTE_PACK_INVALID - SCH_INVALID_ENTITY_TYPE - SCH_SCHEMA_ADAPTATION_FAILED - NET_TIMEOUT - NET_DOWNSTREAM_UNAVAILABLE - NET_CALLBACK_FAILED - NET_ACK_TIMEOUT - NET_OVERLOADED - NET_INTERNAL_ERROR - NET_NOT_IMPLEMENTED - NET_CATALOG_SOURCE_UNAVAILABLE - NET_CATALOG_STALE - BIZ_PROVIDER_NOT_FOUND - BIZ_LOCATION_NOT_FOUND - BIZ_CATEGORY_NOT_FOUND - BIZ_ITEM_NOT_FOUND - BIZ_OFFER_NOT_FOUND - BIZ_ADDON_NOT_FOUND - BIZ_ORDER_NOT_FOUND - BIZ_QUANTITY_UNAVAILABLE - BIZ_FULFILLMENT_UNAVAILABLE - BIZ_QUOTE_EXPIRED_OR_CHANGED - BIZ_PRICE_MISMATCH - BIZ_PAYMENT_NOT_SUPPORTED - BIZ_PAYMENT_FAILED - BIZ_TRACKING_NOT_SUPPORTED - BIZ_SUPPORT_NOT_AVAILABLE - BIZ_NO_RESULTS_FOUND - BIZ_INVALID_STATE_TRANSITION - BIZ_ALREADY_CANCELLED - BIZ_ALREADY_CONFIRMED - BIZ_UPDATE_INCONSISTENT - BIZ_INVALID_UPDATE_TARGET - BIZ_INVALID_CANCELLATION_REASON - BIZ_RATING_TARGET_NOT_FOUND - BIZ_INVALID_RATING_VALUE - BIZ_GENERIC_ERROR - POL_CANCELLATION_NOT_ALLOWED - POL_UPDATE_NOT_ALLOWED - POL_GEO_RESTRICTED - POL_ELIGIBILITY_NOT_MET - POL_KYC_REQUIRED - POL_CONSENT_REQUIRED - POL_SANCTIONED_PARTY - POL_CALLER_TRUST_INSUFFICIENT - POL_NP_CAPACITY_EXCEEDED - POL_NP_DORMANT - POL_ENGAGEMENT_REFUSED - POL_GENERIC_ERROR NackDiscretionary: description: "The synchronous rejection body returned when a responding NP\ \ exercises its protocol-level agency to decline engagement for policy-governed\ \ reasons — insufficient caller trust, capacity limits, scheduled inactivity,\ \ or general refusal — without an underlying exception in the received message.\ \ The caller MUST NOT expect an on_* callback.\n\nNackDiscretionary appears\ \ as the response body for 403 responses on action endpoints. The responding\ \ NP produces it; the calling NP MUST treat it as a terminal response for\ \ the current request. NFOs MAY restrict or prohibit discretionary NACKs\ \ for specific actions, domain contexts, or transaction lifecycle stages per\ \ CON-008-20 in NFH-008.\n\nRelationship: Extends the Ack schema with status\ \ constrained to NACK and adds an error field whose code MUST be one of\ \ the POL_ENGAGEMENT_* discretionary refusal codes." type: object required: - message properties: message: type: object required: - status - messageId - error properties: status: type: string const: NACK messageId: type: string format: uuid error: $ref: '#/components/schemas/Error' NackTooManyRequests: description: "The synchronous rejection body returned when the responding NP\ \ has exceeded a request rate limit (AUT_RATE_LIMITED) or a policy-governed\ \ engagement capacity limit (POL_NP_CAPACITY_EXCEEDED). The caller MUST\ \ apply back-off before retrying. Implementations SHOULD include a Retry-After\ \ header on 429 responses.\n\nNackTooManyRequests appears as the response\ \ body for 429 responses on all endpoints.\n\nRelationship: Extends the\ \ Ack schema with status constrained to NACK and an error code constrained\ \ to the two retryable capacity/rate-limit codes." type: object required: - message properties: message: type: object required: - status - messageId - error properties: status: type: string const: NACK messageId: type: string format: uuid error: $ref: '#/components/schemas/Error' CatalogSubscribeAction: type: object deprecated: true description: "The real-world act by which a DS declares interest in receiving\ \ ongoing catalog/push callbacks from the CS (Cataloging Service) for catalogs\ \ matching specified networks and schema types.\n\nThis schema appears in\ \ the Catalog Subscription phase. The DS produces it as the message payload\ \ of a POST /catalog/subscription request; the CS consumes it to create or\ \ update the subscription record.\n\nRelationship: Composes a subscription\ \ object specifying networkIds and optional schemaTypes. At least one of\ \ networkIds or schemaTypes MUST be provided — providing neither results in\ \ 400 NackBadRequest. Updating an inactive subscription reactivates it." required: - subscription properties: subscription: type: object anyOf: - required: - networkIds - required: - schemaTypes properties: networkIds: type: array items: type: string description: >- Registry-registered network identifiers provided by the CN. The CS scopes catalog/push delivery to subscribers whose networkIds match the published catalog's network. schemaTypes: type: array items: type: string description: >- Schema type URIs as published at schema.beckn.io, provided by the CN. The CS filters catalog/push delivery to subscribers whose schemaTypes intersect the published catalog's schema types. An empty array matches all schema types for the specified networks. CatalogSubscription: type: object deprecated: true description: "The persisted subscription record held by the CS (Cataloging Service),\ \ representing a subscriber's (DS) declared interest in receiving catalog/push callbacks\ \ for specific networks and schema types, along with its current lifecycle\ \ status.\n\nCatalogSubscription appears in the Catalog Subscription phase.\ \ The CS produces it as a response to POST /catalog/subscription (creation\ \ or update) and GET /catalog/subscription (listing). The subscriber (DS) consumes\ \ it to confirm subscription state. The identity\ \ of the subscriber (DS) is derived by the CS from the signing key in the Beckn\ \ HTTP Signature Authorization header on each request.\n\nRelationship:\ \ The status field MUST be one of ACTIVE (the subscriber receives catalog/push\ \ callbacks when matching catalogs are published) or INACTIVE (temporarily\ \ paused; can be reactivated via POST update)." required: - subscriptionId - status properties: subscriptionId: type: string format: uuid description: >- UUID v4 assigned by the CS on subscription creation. Stable for the lifetime of the subscription. MUST be supplied by the CN in all subsequent subscription management operations (update, deactivate, pull). networkIds: type: array items: type: string description: >- Registry-registered network identifiers this subscription covers. Sourced from the CatalogSubscribeAction; used by the CS to scope catalog/push delivery. schemaTypes: type: array items: type: string description: >- Schema type URIs this subscription filters on. An empty array matches all schema types for the subscribed networks. status: type: string enum: - ACTIVE - INACTIVE description: >- Lifecycle state assigned and maintained by the CS. ACTIVE — the subscriber receives catalog/push callbacks when matching catalogs are published. INACTIVE — the subscription is paused and receives no callbacks; can be reactivated via POST update. createdAt: type: string format: date-time description: >- ISO 8601 timestamp set by the CS when the subscription was first created. Immutable after creation. updatedAt: type: string format: date-time description: >- ISO 8601 timestamp set by the CS each time the subscription record is modified. Pagination: type: object description: "Metadata accompanying a paginated list response that describes\ \ the size, position, and count of the returned result set, enabling callers\ \ to navigate through large result sets using offset-based pagination.\n\n\ Pagination appears in list responses such as /catalog/subscription and /catalog/search.\ \ The DS (Discovery Service) and CS (Cataloging Service) produce it; the CN\ \ or PN consumes it to determine whether additional pages are available and\ \ to construct subsequent requests.\n\nRelationship: Composed within the response\ \ message objects of /catalog/subscription and /catalog/search endpoints." properties: total: type: integer minimum: 0 description: >- Total number of matching records across the entire result set, not the count in this page. Assigned by the CS. limit: type: integer minimum: 1 description: >- Maximum number of records returned in this page. Assigned by the CS based on the request parameter or CS policy. offset: type: integer minimum: 0 description: >- Zero-based index of the first record in this page relative to the full result set. Assigned by the CS based on the request parameter. CatalogSearchAction: type: object deprecated: true description: "The real-world act by which a caller queries the CS (Cataloging\ \ Service) for indexed catalogs, applying optional catalog type, network,\ \ and schema type filters with pagination control.\n\nThis schema appears\ \ in the Catalog Search phase. The PN produces it as the message\ \ payload of a POST /catalog/search request; the CS consumes it to filter\ \ and return matching catalogs with pagination metadata.\n\nRelationship: Composed as the message payload of\ \ the /catalog/search request body." additionalProperties: false properties: filters: type: object description: >- Search filters. All fields are optional; omitting a field matches all values for that dimension. properties: type: type: string enum: - MASTER - REGULAR default: MASTER description: >- Restricts results to catalogs of the specified type. MASTER — canonical resource definitions reusable across the network. REGULAR — provider-specific catalogs that may extend master resources. Defaults to MASTER when omitted, preserving backward-compatible behaviour for existing implementations. networkIds: type: array items: type: string description: Filter by network IDs (empty or omitted = all networks) schemaTypes: type: array items: type: string description: Filter by schema type URIs (empty or omitted = all types) limit: type: integer minimum: 1 maximum: 100 default: 20 description: Maximum number of catalogs to return per page offset: type: integer minimum: 0 default: 0 description: Zero-based result offset for pagination CatalogPullAction: type: object deprecated: true description: "The real-world act by which a subscriber (DS) initiates an asynchronous\ \ bulk catalog retrieval from the CS (Cataloging Service), scoped to an active\ \ subscription, specifying whether to retrieve the latest version of each\ \ matching catalog (FULL mode) or all catalog versions within a date range\ \ (INCREMENTAL mode).\n\nThis schema appears in the Catalog Pull phase. The\ \ subscriber (DS) produces it as the message payload of a /catalog/pull request;\ \ the CS consumes it to process the pull request asynchronously and deliver\ \ results via a callback to the subscriber's (DS) /catalog/on_pull endpoint.\n\n\ Relationship: Composed as the message payload of the\ \ /catalog/pull request body. References a CatalogSubscription by subscriptionId." additionalProperties: false required: - subscriptionId properties: subscriptionId: type: string format: uuid description: >- ID of an active CatalogSubscription owned by the caller. The catalog system uses the subscription's networkIds and schemaTypes to determine which catalogs to return. mode: type: string enum: - FULL - INCREMENTAL default: FULL description: >- - `FULL` — returns the latest version of each matching catalog. - `INCREMENTAL` — returns all catalog versions published between `fromDate` and `toDate` (inclusive). fromDate: type: string format: date-time description: >- Inclusive lower bound for INCREMENTAL mode. When omitted in INCREMENTAL mode, defaults to 7 days before the current time. toDate: type: string format: date-time description: >- Inclusive upper bound for INCREMENTAL mode. When omitted, defaults to the current time. limit: type: integer minimum: 1 maximum: 100 default: 20 description: Maximum number of catalogs to return per page offset: type: integer minimum: 0 default: 0 description: Zero-based result offset for pagination CatalogPullCallbackAction: type: object deprecated: true description: "The real-world act by which the CS (Cataloging Service) delivers\ \ the results of a previously accepted /catalog/pull request to the subscriber's (DS)\ \ /catalog/on_pull callback endpoint.\n\nThis schema appears in the Catalog\ \ Pull phase. The CS produces it as the message payload of the async callback;\ \ the subscriber (DS) consumes it to retrieve the requested catalog data.\n\n\ When the result is small it is returned inline in `catalogs`; when the\ \ result is too large to return inline the callback carries a `downloadManifest`\ \ for downloading the result.\n\nRelationship: Composed as the message payload\ \ of the /catalog/on_pull callback. The DS MUST use context.messageId\ \ to correlate this callback with the originating /catalog/pull request." additionalProperties: false required: - status properties: status: type: string enum: - COMPLETED - FAILED description: >- Status of the pull request result assigned by the CS. COMPLETED — the CS successfully assembled the catalog result; the DS MUST process either catalogs[] or downloadManifest. FAILED — the CS could not assemble the result; the DS MUST read the error field and MUST NOT attempt to process catalogs or downloadManifest. catalogs: type: array description: Requested catalogs inline. Present when status is COMPLETED. items: $ref: '#/components/schemas/Catalog' downloadManifest: type: object description: >- Metadata required to download, verify, and decode the catalog result payload from object storage. Present when status is COMPLETED and the result is too large to return inline in catalogs[]. Mutually exclusive with catalogs[] — exactly one MUST be present when status is COMPLETED. The CN MUST download the object at url, verify the checksum before processing, and MUST NOT process the content if verification fails. additionalProperties: false required: - url - format - sizeBytes - checksum - expiresAt properties: url: type: string description: >- Pre-signed object-store URL from which the catalog payload can be downloaded. The DS MUST NOT attempt to download after expiresAt. expiresAt: type: string format: date-time description: >- ISO 8601 timestamp after which url is no longer valid. The DS MUST NOT attempt to download after this time; if expired, the DS MUST re-issue POST /catalog/pull. format: type: string enum: - json - json.gz description: >- Encoding format of the downloaded payload. The CN MUST decompress json.gz before parsing. sizeBytes: type: integer minimum: 0 description: >- Size of the payload in bytes after any compression. The DS MAY use this to validate download completeness. checksum: type: string description: >- SHA-256 hex digest of the payload at url, prefixed with sha256:. The DS MUST verify this against the downloaded content before processing. If verification fails, the DS MUST discard the content and treat the pull as failed. pagination: $ref: '#/components/schemas/Pagination' error: description: Present when status is FAILED. $ref: '#/components/schemas/Error' CatalogSubscriptionResponse: deprecated: true description: "The response envelope returned synchronously by the CS (Cataloging\ \ Service) for subscription management operations — create, update, list,\ \ and deactivate.\n\nThis schema appears in the Catalog Subscription phase.\ \ The CS produces it as the synchronous response to POST /catalog/subscription\ \ (creation or update), GET /catalog/subscription (listing), and DELETE\ \ /catalog/subscription (deactivation). The DS consumes it to confirm subscription\ \ state. No async callback\ \ is delivered for subscription management operations. The context.action\ \ is always catalog/on_subscription.\n\nRelationship: Composes one or more\ \ CatalogSubscription records in the message.subscriptions array, and an\ \ optional Pagination object for list responses." type: object required: - context - message properties: context: allOf: - $ref: '#/components/schemas/Context' - type: object properties: action: type: string const: catalog/on_subscription message: type: object required: - subscriptions properties: subscriptions: type: array items: $ref: '#/components/schemas/CatalogSubscription' pagination: $ref: '#/components/schemas/Pagination' NackForbidden: description: "The synchronous rejection body returned when the caller is authenticated\ \ but does not have permission to access or modify the requested resource.\n\ \nNackForbidden appears as the response body for 403 responses. The implementing\ \ actor produces it; the calling actor MUST NOT retry without correcting\ \ its authorization.\n\nRelationship: Extends the Ack schema with status constrained\ \ to NACK and adds an error field describing the authorization failure." type: object required: - message properties: message: type: object required: - status - messageId - error properties: status: type: string const: NACK messageId: type: string description: >- Echoes the messageId from the triggering request's Context, for caller correlation. error: $ref: '#/components/schemas/Error' NackConflict: description: "The synchronous rejection body returned when the request conflicts\ \ with existing state — for example, a subscription with the same criteria\ \ already exists for this subscriber.\n\nNackConflict appears as the response\ \ body for 409 responses on synchronous endpoints where the conflict is with\ \ persisted resource state, not with callback processing. The implementing\ \ actor produces it; the calling actor MUST resolve the conflict (e.g., update\ \ the existing resource) before retrying.\n\nRelationship: Extends the Ack\ \ schema with status constrained to NACK and adds an error field describing\ \ the conflict." type: object required: - message properties: message: type: object required: - status - messageId - error properties: status: type: string const: NACK messageId: type: string description: >- Echoes the messageId from the triggering request's Context, for caller correlation. error: $ref: '#/components/schemas/Error' NackNotFound: description: "The synchronous rejection body returned when the requested resource\ \ does not exist in the system.\n\nNackNotFound appears as the response body\ \ for 404 responses. The implementing actor produces it; the calling actor\ \ MUST NOT retry without correcting the resource identifier.\n\nRelationship:\ \ Extends the Ack schema with status constrained to NACK and adds an error\ \ field describing why the resource was not found." type: object required: - message properties: message: type: object required: - status - messageId - error properties: status: type: string const: NACK messageId: type: string description: >- Echoes the messageId from the triggering request's Context, for caller correlation. error: $ref: '#/components/schemas/Error' responses: Ack: description: "The implementer has authenticated the request, accepted it for\ \ processing, and MUST deliver the business outcome asynchronously via the\ \ corresponding callback endpoint. The Signature response header carries the\ \ implementer's authenticated receipt." headers: Signature: $ref: '#/components/headers/AckSignatureHeader' content: application/json: schema: $ref: '#/components/schemas/Ack' AckNoCallback: description: "The implementer has received and authenticated the request but\ \ cannot produce a callback — for example, no matching catalog was found,\ \ inventory is unavailable, or the provider is closed. The response body carries\ \ an Error explaining why no callback will follow." headers: Signature: $ref: '#/components/headers/AckSignatureHeader' content: application/json: schema: $ref: '#/components/schemas/AckNoCallback' NackBadRequest: description: "The request body is structurally invalid, missing required fields,\ \ or carries a value that fails semantic validation. The implementer MUST NOT\ \ process the request further. The caller MUST correct the request before retrying." headers: Signature: $ref: '#/components/headers/AckSignatureHeader' content: application/json: schema: $ref: '#/components/schemas/NackBadRequest' NackUnauthorized: description: "The Beckn HTTP Signature on the request is absent, expired, or\ \ fails verification against the sender's public key returned by the subnet\ \ registry lookup. The implementer MUST NOT process the request further. The\ \ caller MUST correct its signing credential or key registration before retrying." headers: Signature: $ref: '#/components/headers/AckSignatureHeader' content: application/json: schema: $ref: '#/components/schemas/NackUnauthorized' ServerError: description: "An unexpected internal failure prevented the implementer from\ \ processing the request. The caller SHOULD treat this as a transient error\ \ and MAY retry after a backoff interval. The response body MAY contain an\ \ error object with additional diagnostic detail." headers: Signature: $ref: '#/components/headers/AckSignatureHeader' content: application/json: schema: $ref: '#/components/schemas/ServerError' NackDiscretionary: description: "The responding NP has declined engagement for policy-governed\ \ reasons unrelated to a protocol error in the request (insufficient caller\ \ trust, capacity limits, scheduled inactivity, or general refusal). The\ \ caller MUST NOT expect an on_* callback. NFOs MAY restrict or prohibit\ \ discretionary NACKs per CON-008-20." headers: Signature: $ref: '#/components/headers/AckSignatureHeader' content: application/json: schema: $ref: '#/components/schemas/NackDiscretionary' NackTooManyRequests: description: "Rate limit or policy-governed capacity limit exceeded. The caller\ \ MUST apply back-off before retrying. Implementations SHOULD include a\ \ Retry-After header indicating when the caller MAY retry." headers: Signature: $ref: '#/components/headers/AckSignatureHeader' Retry-After: description: "Number of seconds (integer) or HTTP-date after which the\ \ caller MAY retry the request." schema: type: string content: application/json: schema: $ref: '#/components/schemas/NackTooManyRequests' NackForbidden: description: Caller is authenticated but does not have permission to access or modify this resource. headers: Signature: $ref: '#/components/headers/AckSignatureHeader' content: application/json: schema: $ref: '#/components/schemas/NackForbidden' NackNotFound: description: The requested resource does not exist. headers: Signature: $ref: '#/components/headers/AckSignatureHeader' content: application/json: schema: $ref: '#/components/schemas/NackNotFound' NackConflict: description: "The request conflicts with existing state. For example, a subscription\ \ with the same criteria already exists for this subscriber. The caller MUST\ \ resolve the conflict (e.g., update the existing resource) before retrying." headers: Signature: $ref: '#/components/headers/AckSignatureHeader' content: application/json: schema: $ref: '#/components/schemas/NackConflict'