openapi: 3.1.0 info: title: Beckn-ONIX Specification description: Transaction Layer APIs for Beckn-ONIX Specification. version: "0.1" servers: - url: https://ps-bap-client.becknprotocol.io description: BOC Network paths: /search: post: tags: - Beckn Provider Platform(BPP) - Beckn Gateway (BG) description: Consumer Interface declares the customer's intent to buy/avail products or services requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: "#/components/schemas/Context" - properties: action: enum: - search message: type: object properties: intent: $ref: "#/components/schemas/Intent" required: - context - message responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /select: post: tags: - Beckn Provider Platform(BPP) description: Consumer Interface declares the customer's cart (or equivalent) created by selecting objects from the catalog requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: "#/components/schemas/Context" - properties: action: enum: - select required: - action message: type: object properties: order: $ref: "#/components/schemas/Order" required: - order required: - context - message responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /init: post: tags: - Beckn Provider Platform(BPP) description: Initialize an order by providing billing and/or shipping details requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: "#/components/schemas/Context" - properties: action: enum: - init required: - action message: type: object properties: order: $ref: "#/components/schemas/Order" required: - order required: - context - message responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /confirm: post: tags: - Beckn Provider Platform(BPP) description: Initialize an order by providing billing and/or shipping details requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: "#/components/schemas/Context" - properties: action: enum: - confirm required: - action message: type: object properties: order: $ref: "#/components/schemas/Order" required: - order required: - context - message responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /status: post: tags: - Beckn Provider Platform(BPP) description: Fetch the latest order object requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: "#/components/schemas/Context" - properties: action: enum: - status required: - action message: type: object properties: order_id: $ref: "#/components/schemas/Order/properties/id" required: - order_id required: - context - message responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /track: post: tags: - Beckn Provider Platform(BPP) description: Track an active order requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: "#/components/schemas/Context" - properties: action: enum: - track required: - action message: type: object properties: order_id: $ref: "#/components/schemas/Order/properties/id" callback_url: type: string format: uri required: - order_id required: - context - message responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /cancel: post: tags: - Beckn Provider Platform(BPP) description: Cancel an order requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: "#/components/schemas/Context" - properties: action: enum: - cancel required: - action message: type: object properties: order_id: $ref: "#/components/schemas/Order/properties/id" cancellation_reason_id: $ref: "#/components/schemas/Option/properties/id" descriptor: $ref: "#/components/schemas/Descriptor" required: - order_id required: - context - message responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /update: post: tags: - Beckn Provider Platform(BPP) description: Remove object requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: "#/components/schemas/Context" - properties: action: enum: - update required: - action message: type: object properties: update_target: description: 'Comma separated values of order objects being updated. For example: ```"update_target":"item,billing,fulfillment"```' type: string order: description: Updated order object allOf: - $ref: "#/components/schemas/Order" required: - update_target - order required: - context - message responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /rating: post: tags: - Beckn Provider Platform(BPP) description: Provide feedback on a service requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: "#/components/schemas/Context" - properties: action: enum: - rating required: - action message: type: object properties: ratings: type: array items: $ref: "#/components/schemas/Rating" required: - context - message responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /support: post: tags: - Beckn Provider Platform(BPP) description: Fetch support information requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: "#/components/schemas/Context" - properties: action: enum: - support required: - action message: type: object properties: support: $ref: "#/components/schemas/Support" required: - context - message responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /get_cancellation_reasons: post: tags: - Beckn Provider Platform(BPP) description: BAP fetches the list of cancellation reasons from BPP requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: '#/components/schemas/Context' - properties: action: enum: - get_cancellation_reasons required: - action required: - context responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /get_return_reasons: post: tags: - Beckn Provider Platform(BPP) description: BAP requests BPP to provide the list of return reasons requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: '#/components/schemas/Context' - properties: action: enum: - get_return_reasons required: - action required: - context responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /get_rating_categories: post: tags: - Beckn Provider Platform(BPP) description: BAP requests BPP to provide the list of entities that can be rated on its system requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: '#/components/schemas/Context' - properties: action: enum: - get_rating_categories required: - action required: - context responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /on_search: post: tags: - Beckn Application Platform(BAP) description: Provider Platform sends its catalog in response to a search request. requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: "#/components/schemas/Context" - properties: action: enum: - on_search required: - action message: type: object properties: catalog: $ref: "#/components/schemas/Catalog" required: - catalog error: $ref: "#/components/schemas/Error" required: - context responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /on_select: post: tags: - Beckn Application Platform(BAP) description: Send draft order object with quoted price for selected items requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: "#/components/schemas/Context" - properties: action: enum: - on_select required: - action message: type: object properties: order: $ref: "#/components/schemas/Order" error: $ref: "#/components/schemas/Error" required: - context responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /on_init: post: tags: - Beckn Application Platform(BAP) description: Send order object with payment details updated requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: "#/components/schemas/Context" - properties: action: enum: - on_init required: - action message: type: object properties: order: $ref: "#/components/schemas/Order" required: - order error: $ref: "#/components/schemas/Error" required: - context responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /on_confirm: post: tags: - Beckn Application Platform(BAP) description: Send active order object requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: "#/components/schemas/Context" - properties: action: enum: - on_confirm required: - action message: type: object properties: order: $ref: "#/components/schemas/Order" required: - order error: $ref: "#/components/schemas/Error" required: - context responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /on_track: post: tags: - Beckn Application Platform(BAP) description: Send tracking details of an active order requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: "#/components/schemas/Context" - properties: action: enum: - on_track required: - action message: type: object properties: tracking: $ref: "#/components/schemas/Tracking" required: - tracking error: $ref: "#/components/schemas/Error" required: - context responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /on_cancel: post: tags: - Beckn Application Platform(BAP) description: Send cancellation request_id with reasons list in case of cancellation request. Else send cancelled order object requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: "#/components/schemas/Context" - properties: action: enum: - on_cancel required: - action message: type: object properties: order: $ref: "#/components/schemas/Order" required: - order error: $ref: "#/components/schemas/Error" required: - context responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /on_update: post: tags: - Beckn Application Platform(BAP) description: Returns updated service with updated runtime object requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: "#/components/schemas/Context" - properties: action: enum: - on_update required: - action message: type: object properties: order: $ref: "#/components/schemas/Order" required: - order error: $ref: "#/components/schemas/Error" required: - context responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /on_status: post: tags: - Beckn Application Platform(BAP) description: Fetch the status of a Service requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: "#/components/schemas/Context" - properties: action: enum: - on_status required: - action message: type: object properties: order: $ref: "#/components/schemas/Order" required: - order error: $ref: "#/components/schemas/Error" required: - context responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /on_rating: post: tags: - Beckn Application Platform(BAP) description: Provide feedback on a service requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: "#/components/schemas/Context" - properties: action: enum: - on_rating required: - action message: type: object properties: feedback_form: description: A feedback form to allow the user to provide additional information on the rating provided allOf: - $ref: "#/components/schemas/XInput" error: $ref: "#/components/schemas/Error" required: - context - message responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /on_support: post: tags: - Beckn Application Platform(BAP) description: Contact Support requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: "#/components/schemas/Context" - properties: action: enum: - on_support required: - action message: type: object properties: support: $ref: "#/components/schemas/Support" error: $ref: "#/components/schemas/Error" required: - context responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /return_reasons: post: tags: - Beckn Application Platform(BAP) description: BPP provides the list of return reasons to the BAP requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: '#/components/schemas/Context' - properties: action: enum: - return_reasons required: - action message: type: object properties: return_reasons: type: array items: $ref: '#/components/schemas/Option' required: - return_reasons required: - context - message responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /rating_categories: post: tags: - Beckn Application Platform(BAP) description: BPP provides the list of entities that can be rated in its system to the BAP requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: '#/components/schemas/Context' - properties: action: enum: - rating_categories required: - action message: type: object properties: rating_categories: type: array items: $ref: '#/components/schemas/Rating/properties/rating_category' required: - return_reasons required: - context - message responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /cancellation_reasons: post: tags: - Beckn Application Platform(BAP) description: BPP sends cancellation reasons to BAP requestBody: content: application/json: schema: type: object properties: context: allOf: - $ref: '#/components/schemas/Context' - properties: action: enum: - cancellation_reasons required: - action message: type: object properties: cancellation_reasons: type: array items: $ref: '#/components/schemas/Option' required: - cancellation_reasons required: - context - message responses: default: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object properties: message: type: object properties: ack: $ref: "#/components/schemas/Ack" required: - ack error: $ref: "#/components/schemas/Error" required: - message /lookup: description: Look up platforms listed on the network registry. This is a protected endpoint only accessible to network participants that have subscribed to the network (i.e Subscribers). Any subscriber can query the Registry by sending a `Lookup` object. The Registry will respond with all the platforms that match the lookup parameters. post: tags: - Registry requestBody: content: application/json: schema: $ref: '#/components/schemas/Subscription' responses: default: description: Array of subscribers matching the lookup request attributes content: application/json: schema: type: array items: $ref: '#/components/schemas/Subscription' /subscribe: description: 'Subscribe to a network. This endpoint allows registered network participants (a.k.a Subscribers), to update their subscription details like `domain`, `location`, `signing_public_key`, `encr_public_key` on the registry. The fields that can be updated can vary from network to network. Every network policy must contain the fields that can be updated for each type of subscriber. For example, the network policy may allow BAPs and BPPs to update all fields, but BGs may not be allowed to update any field except the public keys.' post: tags: - Registry requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/Subscription' - properties: nonce: description: A randomly generated uuid nonce value type: string format: uuid responses: default: description: The Registry returns the status of the subscription request. content: application/json: schema: type: object properties: status: type: string enum: - UNDER_SUBSCRIPTION /on_subscribe: description: 'This endpoint is implemented by all platforms that have successfully passed the certification and compliance requirements on a network. In this endpoint, the Subscriber receives an encrypted challenge string generated by the Registry to verify the subscription details of the Network Participant sent during the `subscribe` call. During this call, Registry also validates the SSL certificate of Subscriber. If the SSL certificate is invalid, the Registry will update the subscriber’s status = INVALID_SSL and call the Subscriber''s `on_subscribe` endpoint again. Anytime the state of the Subscriber changes in the registry, the Registry can make an unsolicited call to the subscriber''s `on_subscribe` endpoint. This request must be digitally signed by the Registry. The Registry''s public key must be published at a publicly accessible trusted location so that the Subscribers can save it on their systems.' post: tags: - Beckn Provider Platform(BPP) - Beckn Application Platform(BAP) - Beckn Gateway (BG) requestBody: content: application/json: schema: type: object properties: status: description: The current status of the Registrant type: string enum: - INITIATED - UNDER_SUBSCRIPTION - SUBSCRIBED - INVALID_SSL - UNSUBSCRIBED challenge: type: string description: A random string generated by the registry encrypted with the subscriber's encryption public key required: - challenge responses: default: description: Network Participant decrypts the challenge string using its private key and returns the decrypted value. content: application/json: schema: type: object properties: answer: description: Decrypted challenge string type: string required: - answer components: schemas: Ack: description: "Describes the acknowledgement sent in response to an API call. If the implementation uses HTTP/S, then Ack must be returned in the same session. Every API call to a Provider Platform must be responded to with an Ack whether the Provider Platform intends to respond with a callback or not. This has one property called `status` that indicates the status of the Acknowledgement." type: object properties: status: type: string description: "The status of the acknowledgement. If the request passes the validation criteria of the Provider Platform, then this is set to ACK. If a Provider Platform responds with status = `ACK` to a request, it is required to respond with a callback. If the request fails the validation criteria, then this is set to NACK. Additionally, if a Provider Platform does not intend to respond with a callback even after the request meets the validation criteria, it should set this value to `NACK`." enum: - ACK - NACK tags: description: A list of tags containing any additional information sent along with the Acknowledgement. type: array items: $ref: "#/components/schemas/TagGroup" AddOn: description: Describes an additional item offered as a value-addition to a product or service. This does not exist independently in a catalog and is always associated with an item. type: object properties: id: description: Provider-defined ID of the add-on type: string descriptor: $ref: "#/components/schemas/Descriptor" price: $ref: "#/components/schemas/Price" Address: description: Describes a postal address. type: string Agent: description: "Describes the direct performer, driver or executor that fulfills an order. It is usually a person. But in some rare cases, it could be a non-living entity like a drone, or a bot. Some examples of agents are Doctor in the healthcare sector, a driver in the mobility sector, or a delivery person in the logistics sector. This object can be set at any stage of the order lifecycle. This can be set at the discovery stage when the Provider Platform wants to provide details on the agent fulfilling the order, like in healthcare, where the doctor's name appears during search. This object can also used to search for a particular person that the customer wants fulfilling an order. Sometimes, this object gets instantiated after the order is confirmed, like in the case of on-demand taxis, where the driver is assigned after the user confirms the ride." properties: id: type: string person: $ref: "#/components/schemas/Person" contact: $ref: "#/components/schemas/Contact" organization: $ref: "#/components/schemas/Organization" rating: $ref: "#/components/schemas/Rating/properties/value" Authorization: description: "Describes an authorization mechanism used to start or end the fulfillment of an order. For example, in the mobility sector, the driver may require a one-time password to initiate the ride. In the healthcare sector, a patient may need to provide a password to open a video conference link during a teleconsultation." type: object properties: type: description: Type of authorization mechanism used. The allowed values for this field can be published as part of the network policy. type: string token: description: "Token used for authorization. This is typically generated at the Provider Platform. The Consumer Interface can send this value to the user via any channel that it uses to authenticate the user like SMS, Email, Push notification, or in-app rendering." type: string valid_from: description: Timestamp in RFC3339 format from which token is valid type: string format: date-time valid_to: description: Timestamp in RFC3339 format until which token is valid type: string format: date-time status: description: Status of the token type: string Billing: description: "Describes the billing details of an entity.
This has properties like name,organization,address,email,phone,time,tax_number, created_at,updated_at" type: object properties: name: description: Name of the billable entity type: string organization: description: Details of the organization being billed. allOf: - $ref: "#/components/schemas/Organization" address: description: The address of the billable entity allOf: - $ref: "#/components/schemas/Address" state: description: The state where the billable entity resides. This is important for state-level tax calculation allOf: - $ref: "#/components/schemas/State" city: description: The city where the billable entity resides. allOf: - $ref: "#/components/schemas/City" email: description: Email address where the bill is sent to type: string format: email phone: description: Phone number of the billable entity type: string time: description: Details regarding the billing period allOf: - $ref: "#/components/schemas/Time" tax_id: description: ID of the billable entity as recognized by the taxation authority type: string Cancellation: description: Describes a cancellation event type: object properties: time: description: Date-time when the order was cancelled by the buyer type: string format: date-time cancelled_by: type: string enum: - CONSUMER - PROVIDER reason: description: The reason for cancellation allOf: - $ref: "#/components/schemas/Option" additional_description: description: Any additional information regarding the nature of cancellation allOf: - $ref: "#/components/schemas/Descriptor" CancellationTerm: description: Describes the cancellation terms of an item or an order. This can be referenced at an item or order level. Item-level cancellation terms can override the terms at the order level. type: object properties: fulfillment_state: description: The state of fulfillment during which this term is applicable. allOf: - $ref: "#/components/schemas/FulfillmentState" reason_required: description: Indicates whether a reason is required to cancel the order type: boolean cancel_by: description: Information related to the time of cancellation. allOf: - $ref: "#/components/schemas/Time" cancellation_fee: $ref: "#/components/schemas/Fee" xinput: $ref: "#/components/schemas/XInput" external_ref: $ref: "#/components/schemas/MediaFile" Catalog: description: "Describes the products or services offered by a Provider Platform. This is typically sent as the response to a search intent from a Consumer Interface. The payment terms, offers and terms of fulfillment supported by the Provider Platform can also be included here. The Provider Platform can show hierarchical nature of products/services in its catalog using the parent_category_id in categories. The Provider Platform can also send a ttl (time to live) in the context which is the duration for which a Consumer Interface can cache the catalog and use the cached catalog.
This has properties like bbp/descriptor,bbp/categories,bbp/fulfillments,bbp/payments,bbp/offers,bbp/providers and exp
This is used in the following situations.
" type: object properties: descriptor: $ref: "#/components/schemas/Descriptor" fulfillments: description: Fulfillment modes offered at the Provider Platform level. This is used when a Provider Platform itself offers fulfillments on behalf of the providers it has onboarded. type: array items: $ref: "#/components/schemas/Fulfillment" payments: description: Payment terms offered by the Provider Platform for all transactions. This can be overriden at the provider level. type: array items: $ref: "#/components/schemas/Payment" offers: description: Offers at the Provider Platform-level. This is common across all providers onboarded by the Provider Platform. type: array items: $ref: "#/components/schemas/Offer" providers: type: array items: $ref: "#/components/schemas/Provider" exp: description: Timestamp after which catalog will expire type: string format: date-time ttl: description: Duration in seconds after which this catalog will expire type: string Category: description: A label under which a collection of items can be grouped. type: object properties: id: description: ID of the category type: string parent_category_id: $ref: "#/components/schemas/Category/properties/id" descriptor: $ref: "#/components/schemas/Descriptor" time: $ref: "#/components/schemas/Time" ttl: description: Time to live for an instance of this schema tags: type: array items: $ref: "#/components/schemas/TagGroup" Circle: description: Describes a circular region of a specified radius centered at a specified GPS coordinate. type: object properties: gps: $ref: "#/components/schemas/Gps" radius: $ref: "#/components/schemas/Scalar" City: description: Describes a city type: object properties: name: description: Name of the city type: string code: description: City code type: string Contact: description: Describes the contact information of an entity type: object properties: phone: type: string email: type: string jcard: type: object description: A Jcard object as per draft-ietf-jcardcal-jcard-03 specification Context: description: "Every API call in beckn protocol has a context. It provides a high-level overview to the receiver about the nature of the intended transaction. Typically, it is the Consumer Interface that sets the transaction context based on the consumer's location and action on their UI. But sometimes, during unsolicited callbacks, the Provider Platform also sets the transaction context but it is usually the same as the context of a previous full-cycle, request-callback interaction between the Consumer Interface and the Provider Platform. The context object contains four types of fields.
  1. Demographic information about the transaction using fields like `domain`, `country`, and `region`.
  2. Addressing details like the sending and receiving platform's ID and API URL.
  3. Interoperability information like the protocol version that implemented by the sender and,
  4. Transaction details like the method being called at the receiver's endpoint, the transaction_id that represents an end-to-end user session at the Consumer Interface, a message ID to pair requests with callbacks, a timestamp to capture sending times, a ttl to specifiy the validity of the request, and a key to encrypt information if necessary.
This object must be passed in every interaction between a Consumer Interface and a Provider Platform. In HTTP/S implementations, it is not necessary to send the context during the synchronous response. However, in asynchronous protocols, the context must be sent during all interactions," type: object properties: domain: description: Domain code that is relevant to this transaction context allOf: - $ref: "#/components/schemas/Domain/properties/code" location: description: The location where the transaction is intended to be fulfilled. allOf: - $ref: "#/components/schemas/Location" action: description: The Beckn protocol method being called by the sender and executed at the receiver. type: string version: type: string description: Version of transaction protocol being used by the sender. bap_id: description: Subscriber ID of the Consumer Interface allOf: - description: "A globally unique identifier of the platform, Typically it is the fully qualified domain name (FQDN) of the platform." type: string bap_uri: description: Subscriber URL of the Consumer Interface for accepting callbacks from Provider Platforms. allOf: - description: The callback URL of the Subscriber. This should necessarily contain the same domain name as set in `subscriber_id``. type: string format: uri bpp_id: description: Subscriber ID of the Provider Platform allOf: - $ref: "#/components/schemas/Context/properties/bap_id/allOf/0" bpp_uri: description: Subscriber URL of the Provider Platform for accepting calls from Consumer Interfaces. allOf: - $ref: "#/components/schemas/Context/properties/bap_uri/allOf/0" transaction_id: description: "This is a unique value which persists across all API calls from `search` through `confirm`. This is done to indicate an active user session across multiple requests. The Provider Platforms can use this value to push personalized recommendations, and dynamic offerings related to an ongoing transaction despite being unaware of the user active on the Consumer Interface." type: string format: uuid message_id: description: "This is a unique value which persists during a request / callback cycle. Since beckn protocol APIs are asynchronous, Consumer Interfaces need a common value to match an incoming callback from a Provider Platform to an earlier call. This value can also be used to ignore duplicate messages coming from the Provider Platform. It is recommended to generate a fresh message_id for every new interaction. When sending unsolicited callbacks, Provider Platforms must generate a new message_id." type: string format: uuid timestamp: description: Time of request generation in RFC3339 format type: string format: date-time key: description: The encryption public key of the sender type: string ttl: description: The duration in ISO8601 format after timestamp for which this message holds valid type: string Country: description: Describes a country type: object properties: name: type: string description: Name of the country code: type: string description: Country code as per ISO 3166-1 and ISO 3166-2 format Credential: description: Describes a credential of an entity - Person or Organization type: object properties: id: type: string type: type: string default: VerifiableCredential url: description: URL of the credential type: string format: uri Customer: description: Describes a customer buying/availing a product or a service type: object properties: person: $ref: "#/components/schemas/Person" contact: $ref: "#/components/schemas/Contact" DecimalValue: description: Describes a numerical value in decimal form type: string pattern: "[+-]?([0-9]*[.])?[0-9]+" Descriptor: description: Physical description of something. type: object properties: name: type: string code: type: string short_desc: type: string long_desc: type: string additional_desc: type: object properties: url: type: string content_type: type: string enum: - text/plain - text/html - application/json media: type: array items: $ref: "#/components/schemas/MediaFile" images: type: array items: $ref: "#/components/schemas/Image" Domain: description: "Described the industry sector or sub-sector. The network policy should contain codes for all the industry sectors supported by the network. Domains can be created in varying levels of granularity. The granularity of a domain can be decided by the participants of the network. Too broad domains will result in irrelevant search broadcast calls to Provider Platforms that don't have services supporting the domain. Too narrow domains will result in a large number of registry entries for each Provider Platform. It is recommended that network facilitators actively collaborate with various working groups and network participants to carefully choose domain codes keeping in mind relevance, performance, and opportunity cost. It is recommended that networks choose broad domains like mobility, logistics, healthcare etc, and progressively granularize them as and when the number of network participants for each domain grows large." type: object properties: name: description: Name of the domain type: string code: description: "Standard code representing the domain. The standard is usually published as part of the network policy. Furthermore, the network facilitator should also provide a mechanism to provide the supported domains of a network." additional_info: description: A url that contains addtional information about that domain. allOf: - $ref: "#/components/schemas/MediaFile" Duration: description: Describes duration as per ISO8601 format type: string Error: description: "Describes an error object that is returned by a Consumer Interface, Provider Platform or BG as a response or callback to an action by another network participant. This object is sent when any request received by a network participant is unacceptable. This object can be sent either during Ack or with the callback." type: object properties: code: type: string description: 'Standard error code. For full list of error codes, refer to docs/protocol-drafts/BECKN-005-ERROR-CODES-DRAFT-01.md of this repo"' paths: type: string description: Path to json schema generating the error. Used only during json schema validation errors message: type: string description: Human readable message describing the error. Used mainly for logging. Not recommended to be shown to the user. Fee: description: A fee applied on a particular entity type: object properties: percentage: description: Percentage of a value allOf: - $ref: "#/components/schemas/DecimalValue" amount: description: A fixed value allOf: - $ref: "#/components/schemas/Price" Form: description: Describes a form type: object properties: id: type: string description: ID of the form url: description: "The URL from where the form can be fetched. The content fetched from the url must be processed as per the mime_type specified in this object. Once fetched, the rendering platform can choosed to render the form as-is as an embeddable element; or process it further to blend with the theme of the application. In case the interface is non-visual, the the render can process the form data and reproduce it as per the standard specified in the form." type: string format: uri data: description: The form submission data type: object additionalProperties: type: string mime_type: description: This field indicates the nature and format of the form received by querying the url. MIME types are defined and standardized in IETF's RFC 6838. type: string enum: - text/html - application/xml submission_id: type: string format: uuid Fulfillment: description: Describes how a an order will be rendered/fulfilled to the end-customer type: object properties: id: description: Unique reference ID to the fulfillment of an order type: string type: description: "A code that describes the mode of fulfillment. This is typically set when there are multiple ways an order can be fulfilled. For example, a retail order can be fulfilled either via store pickup or a home delivery. Similarly, a medical consultation can be provided either in-person or via tele-consultation. The network policy must publish standard fulfillment type codes for the different modes of fulfillment." type: string rateable: description: Whether the fulfillment can be rated or not type: boolean rating: description: The rating value of the fulfullment service. allOf: - $ref: "#/components/schemas/Rating/properties/value" state: description: The current state of fulfillment. The Provider Platform must set this value whenever the state of the order fulfillment changes and fire an unsolicited `on_status` call. allOf: - $ref: "#/components/schemas/FulfillmentState" tracking: type: boolean description: Indicates whether the fulfillment allows tracking default: false customer: description: The person that will ultimately receive the order allOf: - $ref: "#/components/schemas/Customer" agent: description: The agent that is currently handling the fulfillment of the order allOf: - $ref: "#/components/schemas/Agent" contact: $ref: "#/components/schemas/Contact" vehicle: $ref: "#/components/schemas/Vehicle" stops: description: The list of logical stops encountered during the fulfillment of an order. type: array items: $ref: "#/components/schemas/Stop" path: description: The physical path taken by the agent that can be rendered on a map. The allowed format of this property can be set by the network. type: string tags: type: array items: $ref: "#/components/schemas/TagGroup" FulfillmentState: description: Describes the state of fulfillment type: object properties: descriptor: $ref: "#/components/schemas/Descriptor" updated_at: type: string format: date-time updated_by: type: string description: ID of entity which changed the state Gps: description: Describes a GPS coordinate type: string pattern: '^[-+]?([1-8]?\d(\.\d+)?|90(\.0+)?),\s*[-+]?(180(\.0+)?|((1[0-7]\d)|([1-9]?\d))(\.\d+)?)$' Image: description: Describes an image type: object properties: url: description: URL to the image. This can be a data url or an remote url type: string format: uri size_type: description: The size of the image. The network policy can define the default dimensions of each type type: string enum: - xs - sm - md - lg - xl - custom width: description: Width of the image in pixels type: string height: description: Height of the image in pixels type: string Intent: description: "The intent to buy or avail a product or a service. The Consumer Interface can declare the intent of the consumer containing
This has properties like descriptor,provider,fulfillment,payment,category,offer,item,tags
This is typically used by the Consumer Interface to send the purpose of the user's search to the Provider Platform. This will be used by the Provider Platform to find products or services it offers that may match the user's intent.
For example, in Mobility, the mobility consumer declares a mobility intent. In this case, the mobility consumer declares information that describes various aspects of their journey like,
For example, in health domain, a consumer declares the intent for a lab booking the describes various aspects of their booking like," type: object properties: descriptor: description: "A raw description of the search intent. Free text search strings, raw audio, etc can be sent in this object." allOf: - $ref: "#/components/schemas/Descriptor" provider: description: The provider from which the customer wants to place to the order from allOf: - $ref: "#/components/schemas/Provider" fulfillment: description: Details on how the customer wants their order fulfilled allOf: - $ref: "#/components/schemas/Fulfillment" payment: description: Details on how the customer wants to pay for the order allOf: - $ref: "#/components/schemas/Payment" category: description: Details on the item category allOf: - $ref: "#/components/schemas/Category" offer: description: details on the offer the customer wants to avail allOf: - $ref: "#/components/schemas/Offer" item: description: Details of the item that the consumer wants to order allOf: - $ref: "#/components/schemas/Item" tags: type: array items: $ref: "#/components/schemas/TagGroup" ItemQuantity: description: Describes the count or amount of an item type: object properties: allocated: description: This represents the exact quantity allocated for purchase of the item. type: object properties: count: type: integer minimum: 0 measure: $ref: "#/components/schemas/Scalar" available: description: This represents the exact quantity available for purchase of the item. The buyer can only purchase multiples of this type: object properties: count: type: integer minimum: 0 measure: $ref: "#/components/schemas/Scalar" maximum: description: This represents the maximum quantity allowed for purchase of the item type: object properties: count: type: integer minimum: 1 measure: $ref: "#/components/schemas/Scalar" minimum: description: This represents the minimum quantity allowed for purchase of the item type: object properties: count: type: integer minimum: 0 measure: $ref: "#/components/schemas/Scalar" selected: description: This represents the quantity selected for purchase of the item type: object properties: count: type: integer minimum: 0 measure: $ref: "#/components/schemas/Scalar" unitized: description: This represents the quantity available in a single unit of the item type: object properties: count: type: integer minimum: 1 maximum: 1 measure: $ref: "#/components/schemas/Scalar" Item: description: "Describes a product or a service offered to the end consumer by the provider. In the mobility sector, it can represent a fare product like one way journey. In the logistics sector, it can represent the delivery service offering. In the retail domain it can represent a product like a grocery item." type: object properties: id: description: ID of the item. type: string parent_item_id: description: "ID of the item, this item is a variant of" allOf: - $ref: "#/components/schemas/Item/properties/id" parent_item_quantity: description: The number of units of the parent item this item is a multiple of allOf: - $ref: "#/components/schemas/ItemQuantity" descriptor: description: Physical description of the item allOf: - $ref: "#/components/schemas/Descriptor" creator: description: The creator of this item allOf: - $ref: "#/components/schemas/Organization" price: description: "The price of this item, if it has intrinsic value" allOf: - $ref: "#/components/schemas/Price" quantity: description: The selling quantity of the item allOf: - $ref: "#/components/schemas/ItemQuantity" category_ids: description: Categories this item can be listed under type: array items: allOf: - $ref: "#/components/schemas/Category/properties/id" fulfillment_ids: description: Modes through which this item can be fulfilled type: array items: allOf: - $ref: "#/components/schemas/Fulfillment/properties/id" location_ids: description: Provider Locations this item is available in type: array items: allOf: - $ref: "#/components/schemas/Location/properties/id" payment_ids: description: Payment modalities through which this item can be ordered type: array items: allOf: - $ref: "#/components/schemas/Payment/properties/id" add_ons: type: array items: $ref: "#/components/schemas/AddOn" cancellation_terms: description: Cancellation terms of this item type: array items: $ref: "#/components/schemas/CancellationTerm" refund_terms: description: Refund terms of this item type: array items: description: Refund term of an item or an order type: object properties: fulfillment_state: description: The state of fulfillment during which this term is applicable. allOf: - $ref: "#/components/schemas/State" refund_eligible: description: Indicates if cancellation will result in a refund type: boolean refund_within: description: Time within which refund will be processed after successful cancellation. allOf: - $ref: "#/components/schemas/Time" refund_amount: $ref: "#/components/schemas/Price" replacement_terms: description: Terms that are applicable be met when this item is replaced type: array items: $ref: "#/components/schemas/ReplacementTerm" return_terms: description: Terms that are applicable when this item is returned type: array items: $ref: "#/components/schemas/ReturnTerm" xinput: description: Additional input required from the customer to purchase / avail this item allOf: - $ref: "#/components/schemas/XInput" time: description: Temporal attributes of this item. This property is used when the item exists on the catalog only for a limited period of time. allOf: - $ref: "#/components/schemas/Time" rateable: description: Whether this item can be rated type: boolean rating: description: The rating of the item allOf: - $ref: "#/components/schemas/Rating/properties/value" matched: description: Whether this item is an exact match of the request type: boolean related: description: Whether this item is a related item to the exactly matched item type: boolean recommended: description: Whether this item is a recommended item to a response type: boolean ttl: description: Time to live in seconds for an instance of this schema type: string tags: type: array items: $ref: "#/components/schemas/TagGroup" Location: description: The physical location of something type: object properties: id: type: string descriptor: $ref: "#/components/schemas/Descriptor" map_url: description: The url to the map of the location. This can be a globally recognized map url or the one specified by the network policy. type: string format: uri gps: description: The GPS co-ordinates of this location. allOf: - $ref: "#/components/schemas/Gps" address: description: The address of this location. allOf: - $ref: "#/components/schemas/Address" city: description: "The city this location is, or is located within" allOf: - $ref: "#/components/schemas/City" district: description: "The state this location is, or is located within" type: string state: description: "The state this location is, or is located within" allOf: - $ref: "#/components/schemas/State" country: description: "The country this location is, or is located within" allOf: - $ref: "#/components/schemas/Country" area_code: type: string circle: $ref: "#/components/schemas/Circle" polygon: description: The boundary polygon of this location type: string 3dspace: description: The three dimensional region describing this location type: string rating: description: The rating of this location allOf: - $ref: "#/components/schemas/Rating/properties/value" MediaFile: description: This object contains a url to a media file. type: object properties: mimetype: description: "indicates the nature and format of the document, file, or assortment of bytes. MIME types are defined and standardized in IETF's RFC 6838" type: string url: description: The URL of the file type: string format: uri signature: description: The digital signature of the file signed by the sender type: string dsa: description: The signing algorithm used by the sender type: string Offer: description: An offer associated with a catalog. This is typically used to promote a particular product and enable more purchases. type: object properties: id: type: string descriptor: $ref: "#/components/schemas/Descriptor" location_ids: type: array items: $ref: "#/components/schemas/Location/properties/id" category_ids: type: array items: $ref: "#/components/schemas/Category/properties/id" item_ids: type: array items: $ref: "#/components/schemas/Item/properties/id" time: $ref: "#/components/schemas/Time" tags: type: array items: $ref: "#/components/schemas/TagGroup" Option: description: Describes a selectable option type: object properties: id: type: string descriptor: $ref: "#/components/schemas/Descriptor" Order: description: Describes a legal purchase order. It contains the complete details of the legal contract created between the buyer and the seller. type: object properties: id: type: string description: Human-readable ID of the order. This is generated at the Provider Platform layer. The Provider Platform can either generate order id within its system or forward the order ID created at the provider level. ref_order_ids: description: A list of order IDs to link this order to previous orders. type: array items: type: string description: ID of a previous order status: description: Status of the order. Allowed values can be defined by the network policy type: string enum: - ACTIVE - COMPLETE - CANCELLED type: description: "This is used to indicate the type of order being created to Provider Platforms. Sometimes orders can be linked to previous orders, like a replacement order in a retail domain. A follow-up consultation in healthcare domain. A single order part of a subscription order. The list of order types can be standardized at the network level." type: string default: DEFAULT enum: - DRAFT - DEFAULT provider: description: Details of the provider whose catalog items have been selected. allOf: - $ref: "#/components/schemas/Provider" items: description: The items purchased / availed in this order type: array items: $ref: "#/components/schemas/Item" add_ons: description: The add-ons purchased / availed in this order type: array items: $ref: "#/components/schemas/AddOn" offers: description: The offers applied in this order type: array items: $ref: "#/components/schemas/Offer" billing: description: The billing details of this order allOf: - $ref: "#/components/schemas/Billing" fulfillments: description: The fulfillments involved in completing this order type: array items: $ref: "#/components/schemas/Fulfillment" cancellation: description: The cancellation details of this order allOf: - $ref: "#/components/schemas/Cancellation" cancellation_terms: description: Cancellation terms of this item type: array items: $ref: "#/components/schemas/CancellationTerm" refund_terms: description: Refund terms of this item type: array items: $ref: "#/components/schemas/Item/properties/refund_terms/items" replacement_terms: description: Replacement terms of this item type: array items: $ref: "#/components/schemas/ReplacementTerm" return_terms: description: Return terms of this item type: array items: $ref: "#/components/schemas/ReturnTerm" quote: description: The mutually agreed upon quotation for this order. allOf: - $ref: "#/components/schemas/Quotation" payments: description: The terms of settlement for this order type: array items: $ref: "#/components/schemas/Payment" created_at: description: The date-time of creation of this order type: string format: date-time updated_at: description: The date-time of updated of this order type: string format: date-time xinput: description: Additional input required from the customer to confirm this order allOf: - $ref: "#/components/schemas/XInput" tags: type: array items: $ref: "#/components/schemas/TagGroup" Organization: description: An organization. Usually a recognized business entity. type: object properties: descriptor: $ref: "#/components/schemas/Descriptor" address: description: The postal address of the organization allOf: - $ref: "#/components/schemas/Address" state: description: The state where the organization's address is registered allOf: - $ref: "#/components/schemas/State" city: description: The city where the the organization's address is registered allOf: - $ref: "#/components/schemas/City" contact: $ref: "#/components/schemas/Contact" Payment: description: "Describes the terms of settlement between the Consumer Interface and the Provider Platform for a single transaction. When instantiated, this object contains
  1. the amount that has to be settled,
  2. The payment destination destination details
  3. When the settlement should happen, and
  4. A transaction reference ID
. During a transaction, the Provider Platform reserves the right to decide the terms of payment. However, the Consumer Interface can send its terms to the Provider Platform first. If the Provider Platform does not agree to those terms, it must overwrite the terms and return them to the Consumer Interface. If overridden, the Consumer Interface must either agree to the terms sent by the Provider Platform in order to preserve the provider's autonomy, or abort the transaction. In case of such disagreements, the Consumer Interface and the Provider Platform can perform offline negotiations on the payment terms. Once an agreement is reached, the Consumer Interface and Provider Platform can resume transactions." type: object properties: id: description: ID of the payment term that can be referred at an item or an order level in a catalog type: string collected_by: description: "This field indicates who is the collector of payment. The Consumer Interface can set this value to 'Consumer Interface' if it wants to collect the payment first and settle it to the Provider Platform. If the Provider Platform agrees to those terms, the Provider Platform should not send the payment url. Alternatively, the Provider Platform can set this field with the value 'Provider Platform' if it wants the payment to be made directly." url: type: string description: "A payment url to be called by the Consumer Interface. If empty, then the payment is to be done offline. The details of payment should be present in the params object. If tl_method = http/get, then the payment details will be sent as url params. Two url param values, ```$transaction_id``` and ```$amount``` are mandatory." format: uri params: type: object properties: transaction_id: type: string description: The reference transaction ID associated with a payment activity amount: type: string currency: type: string bank_code: type: string bank_account_number: type: string virtual_payment_address: type: string source_bank_code: type: string source_bank_account_number: type: string source_virtual_payment_address: type: string type: type: string enum: - PRE-ORDER - PRE-FULFILLMENT - ON-FULFILLMENT - POST-FULFILLMENT status: type: string enum: - PAID - NOT-PAID time: $ref: "#/components/schemas/Time" tags: type: array items: $ref: "#/components/schemas/TagGroup" Person: description: Describes a person as any individual type: object properties: id: type: string description: Describes the identity of the person url: description: Profile url of the person type: string format: uri name: description: the name of the person type: string image: $ref: "#/components/schemas/Image" age: description: Age of the person allOf: - $ref: "#/components/schemas/Duration" dob: description: Date of birth of the person type: string format: date gender: type: string description: "Gender of something, typically a Person, but possibly also fictional characters, animals, etc. While Male and Female may be used, text strings are also acceptable for people who do not identify as a binary gender.Allowed values for this field can be published in the network policy" creds: type: array items: $ref: "#/components/schemas/Credential" languages: type: array items: description: Describes a language known to the person. type: object properties: code: type: string name: type: string skills: type: array items: description: Describes a skill of the person. type: object properties: code: type: string name: type: string tags: type: array items: $ref: "#/components/schemas/TagGroup" Price: description: Describes the price of a product or service type: object properties: currency: type: string value: $ref: "#/components/schemas/DecimalValue" estimated_value: $ref: "#/components/schemas/DecimalValue" computed_value: $ref: "#/components/schemas/DecimalValue" listed_value: $ref: "#/components/schemas/DecimalValue" offered_value: $ref: "#/components/schemas/DecimalValue" minimum_value: $ref: "#/components/schemas/DecimalValue" maximum_value: $ref: "#/components/schemas/DecimalValue" Provider: description: Describes the catalog of a business. type: object properties: id: type: string description: Id of the provider descriptor: $ref: "#/components/schemas/Descriptor" category_id: type: string description: Category Id of the provider at the Provider Platform-level catalog rating: $ref: "#/components/schemas/Rating/properties/value" time: $ref: "#/components/schemas/Time" categories: type: array items: $ref: "#/components/schemas/Category" fulfillments: type: array items: $ref: "#/components/schemas/Fulfillment" payments: type: array items: $ref: "#/components/schemas/Payment" locations: type: array items: $ref: "#/components/schemas/Location" offers: type: array items: $ref: "#/components/schemas/Offer" items: type: array items: $ref: "#/components/schemas/Item" exp: type: string description: Time after which catalog has to be refreshed format: date-time rateable: description: Whether this provider can be rated or not type: boolean ttl: description: "The time-to-live in seconds, for this object. This can be overriden at deeper levels. A value of -1 indicates that this object is not cacheable." type: integer minimum: -1 tags: type: array items: $ref: "#/components/schemas/TagGroup" Quotation: description: "Describes a quote. It is the estimated price of products or services from the Provider Platform.
This has properties like price, breakup, ttl" type: object properties: id: description: ID of the quote. type: string format: uuid price: description: The total quoted price allOf: - $ref: "#/components/schemas/Price" breakup: description: the breakup of the total quoted price type: array items: type: object properties: item: $ref: "#/components/schemas/Item" title: type: string price: $ref: "#/components/schemas/Price" ttl: $ref: "#/components/schemas/Duration" Rating: description: Describes the rating of an entity type: object properties: rating_category: description: Category of the entity being rated type: string enum: - Item - Order - Fulfillment - Provider - Agent - Support id: description: Id of the object being rated type: string value: description: "Rating value given to the object. This can be a single value or can also contain an inequality operator like gt, gte, lt, lte. This can also contain an inequality expression containing logical operators like && and ||." type: string Region: description: Describes an arbitrary region of space. The network policy should contain a published list of supported regions by the network. type: object properties: dimensions: description: "The number of dimensions that are used to describe any point inside that region. The most common dimensionality of a region is 2, that represents an area on a map. There are regions on the map that can be approximated to one-dimensional regions like roads, railway lines, or shipping lines. 3 dimensional regions are rarer, but are gaining popularity as flying drones are being adopted for various fulfillment services." type: string enum: - "1" - "2" - "3" type: description: "The type of region. This is used to specify the granularity of the region represented by this object. Various examples of two-dimensional region types are city, country, state, district, and so on. The network policy should contain a list of all possible region types supported by the network." type: string name: type: string description: Name of the region as specified on the map where that region exists. code: type: string description: A standard code representing the region. This should be interpreted in the same way by all network participants. boundary: type: string description: "A string representing the boundary of the region. One-dimensional regions are represented by polylines. Two-dimensional regions are represented by polygons, and three-dimensional regions can represented by polyhedra." map_url: type: string description: The url to the map of the region. This can be a globally recognized map or the one specified by the network policy. ReplacementTerm: description: The replacement policy of an item or an order type: object properties: fulfillment_state: description: The state of fulfillment during which this term is applicable. allOf: - $ref: "#/components/schemas/State" replace_within: description: "Applicable only for buyer managed returns where the buyer has to replace the item before a certain date-time, failing which they will not be eligible for replacement" allOf: - $ref: "#/components/schemas/Time" external_ref: $ref: "#/components/schemas/MediaFile" ReturnTerm: description: Describes the return policy of an item or an order type: object properties: fulfillment_state: description: The state of fulfillment during which this term IETF''s applicable. allOf: - $ref: "#/components/schemas/State" return_eligible: description: Indicates whether the item is eligible for return type: boolean return_time: description: "Applicable only for buyer managed returns where the buyer has to return the item to the origin before a certain date-time, failing which they will not be eligible for refund." allOf: - $ref: "#/components/schemas/Time" return_location: description: The location where the item or order must / will be returned to allOf: - $ref: "#/components/schemas/Location" fulfillment_managed_by: description: The entity that will perform the return type: string enum: - CONSUMER - PROVIDER Scalar: description: Describes a scalar type: object properties: type: type: string enum: - CONSTANT - VARIABLE value: $ref: "#/components/schemas/DecimalValue" estimated_value: $ref: "#/components/schemas/DecimalValue" computed_value: $ref: "#/components/schemas/DecimalValue" range: type: object properties: min: $ref: "#/components/schemas/DecimalValue" max: $ref: "#/components/schemas/DecimalValue" unit: type: string Schedule: description: "Describes schedule as a repeating time period used to describe a regularly recurring event. At a minimum a schedule will specify frequency which describes the interval between occurrences of the event. Additional information can be provided to specify the schedule more precisely. This includes identifying the timestamps(s) of when the event will take place. Schedules may also have holidays to exclude a specific day from the schedule.
This has properties like frequency, holidays, times" type: object properties: frequency: $ref: "#/components/schemas/Duration" holidays: type: array items: type: string format: date-time times: type: array items: type: string format: date-time State: description: A bounded geopolitical region of governance inside a country. type: object properties: name: type: string description: Name of the state code: type: string description: State code as per country or international standards Stop: description: A logical point in space and time during the fulfillment of an order. type: object properties: id: type: string parent_stop_id: type: string location: description: Location of the stop allOf: - $ref: "#/components/schemas/Location" type: description: The type of stop. Allowed values of this property can be defined by the network policy. type: string time: description: Timings applicable at the stop. allOf: - $ref: "#/components/schemas/Time" instructions: description: Instructions that need to be followed at the stop allOf: - $ref: "#/components/schemas/Descriptor" contact: description: Contact details of the stop allOf: - $ref: "#/components/schemas/Contact" person: description: The details of the person present at the stop allOf: - $ref: "#/components/schemas/Person" authorization: $ref: "#/components/schemas/Authorization" Support: description: Details of customer support type: object properties: descriptor: $ref: "#/components/schemas/Descriptor" order_id: type: string callback_phone: type: string format: phone chat: type: object properties: url: description: Chat URL type: string session_id: description: Chat session ID type: string faq: description: Link to the FAQ document type: object properties: url: type: string mime_type: type: string agent: $ref: "#/components/schemas/Agent" Tag: description: "Describes a tag. This is used to contain extended metadata. This object can be added as a property to any schema to describe extended attributes. For Consumer Interfaces, tags can be sent during search to optimize and filter search results. Provider Platforms can use tags to index their catalog to allow better search functionality. Tags are sent by the Provider Platform as part of the catalog response in the `on_search` callback. Tags are also meant for display purposes. Upon receiving a tag, Consumer Interfaces are meant to render them as name-value pairs. This is particularly useful when rendering tabular information about a product or service." type: object properties: descriptor: description: "Description of the Tag, can be used to store detailed information." allOf: - $ref: "#/components/schemas/Descriptor" value: description: The value of the tag. This set by the Provider Platform and rendered as-is by the Consumer Interface. type: string display: description: "This value indicates if the tag is intended for display purposes. If set to `true`, then this tag must be displayed. If it is set to `false`, it should not be displayed. This value can override the group display value." type: boolean TagGroup: description: "A collection of tag objects with group level attributes. For detailed documentation on the Tags and Tag Groups schema go to https://github.com/beckn/protocol-specifications/discussions/316" type: object properties: display: description: "Indicates the display properties of the tag group. If display is set to false, then the group will not be displayed. If it is set to true, it should be displayed. However, group-level display properties can be overriden by individual tag-level display property. As this schema is purely for catalog display purposes, it is not recommended to send this value during search." type: boolean default: true descriptor: description: "Description of the TagGroup, can be used to store detailed information." allOf: - $ref: "#/components/schemas/Descriptor" list: description: "An array of Tag objects listed under this group. This property can be set by Consumer Interfaces during search to narrow the `search` and achieve more relevant results. When received during `on_search`, Consumer Interfaces must render this list under the heading described by the `name` property of this schema." type: array items: $ref: "#/components/schemas/Tag" Time: description: "Describes time in its various forms. It can be a single point in time; duration; or a structured timetable of operations
This has properties like label, time stamp,duration,range, days, schedule" type: object properties: label: type: string timestamp: type: string format: date-time duration: $ref: "#/components/schemas/Duration" range: type: object properties: start: type: string format: date-time end: type: string format: date-time days: type: string description: comma separated values representing days of the week schedule: $ref: "#/components/schemas/Schedule" Tracking: description: Contains tracking information that can be used by the Consumer Interface to track the fulfillment of an order in real-time. which is useful for knowing the location of time sensitive deliveries. type: object properties: id: description: A unique tracking reference number type: string url: description: "A URL to the tracking endpoint. This can be a link to a tracking webpage, a webhook URL created by the Consumer Interface where Provider Platform can push the tracking data, or a GET url creaed by the Provider Platform which the Consumer Interface can poll to get the tracking data. It can also be a websocket URL where the Provider Platform can push real-time tracking data." type: string format: uri location: description: "In case there is no real-time tracking endpoint available, this field will contain the latest location of the entity being tracked. The Provider Platform will update this value everytime the Consumer Interface calls the track API." allOf: - $ref: "#/components/schemas/Location" status: description: "This value indicates if the tracking is currently active or not. If this value is `active`, then the Consumer Interface can begin tracking the order. If this value is `inactive`, the tracking URL is considered to be expired and the Consumer Interface should stop tracking the order." type: string enum: - active - inactive Vehicle: description: "Describes a vehicle is a device that is designed or used to transport people or cargo over land, water, air, or through space.
This has properties like category, capacity, make, model, size,variant,color,energy_type,registration" type: object properties: category: type: string capacity: type: integer make: type: string model: type: string size: type: string variant: type: string color: type: string energy_type: type: string registration: type: string wheels_count: type: string cargo_volumne: type: string wheelchair_access: type: string code: type: string emission_standard: type: string XInput: description: "Contains any additional or extended inputs required to confirm an order. This is typically a Form Input. Sometimes, selection of catalog elements is not enough for the Provider Platform to confirm an order. For example, to confirm a flight ticket, the airline requires details of the passengers along with information on baggage, identity, in addition to the class of ticket. Similarly, a logistics company may require details on the nature of shipment in order to confirm the shipping. A recruiting firm may require additional details on the applicant in order to confirm a job application. For all such purposes, the can choose to send this object attached to any object in the catalog that is required to be sent while placing the order. This object can typically be sent at an item level or at the order level. The item level XInput will override the Order level XInput as it indicates a special requirement of information for that particular item. Hence the Consumer Interface must render a separate form for the Item and another form at the Order level before confirmation." type: object properties: id: type: string head: type: object properties: descriptor: $ref: "#/components/schemas/Form" index: type: object properties: cur: type: integer max: type: integer min: type: integer headings: type: array items: type: string form: $ref: "#/components/schemas/Form" required: description: Indicates whether the form data is mandatorily required by the Provider Platform to confirm the order. type: boolean Subscription: description: Subscription details of a Network Participant. allOf: - $ref: '#/components/schemas/Subscriber' - properties: key_id: description: A unique ID of the subscription entry in a registry. type: string format: uuid signing_public_key: description: The signing public key of the subscriber type: string encr_public_key: description: The encryption public key of the subscriber type: string valid_from: description: Date-time which the signing and encryption keys are valid from type: string format: date-time valid_until: description: Time till which the signing and encryption keys are valid type: string format: date-time status: description: Status of the subscription type: string enum: - INITIATED - UNDER_SUBSCRIPTION - SUBSCRIBED - EXPIRED - UNSUBSCRIBED - INVALID_SSL created: type: string format: date-time updated: type: string format: date-time Subscriber: description: A unique operational configuration of a trusted platform on a network. type: object properties: subscriber_id: description: 'A globally unique identifier of the platform, Typically it is the fully qualified domain name (FQDN) of the platform.' type: string url: description: The callback URL of the Subscriber. This should necessarily contain the same domain name as set in `subscriber_id``. type: string format: uri type: description: The role of subscriber on the network type: string enum: - BAP - BPP - BG domain: description: Operating industry domain that this subscriber offers its products or services in. A single subscriber can operate in multiple domains. Each operating domain must have a unique subscriber object entry in the req allOf: - description: 'Standard code representing the domain. The standard is usually published as part of the network policy. Furthermore, the network facilitator should also provide a mechanism to provide the supported domains of a network.' location: description: The region of operation of this subscriber allOf: - $ref: '#/components/schemas/Location' responses: CatalogResponse: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object additionalProperties: false properties: catalog: $ref: '#/components/schemas/Catalog' requestBodies: CatalogRequest: description: Acknowledgement of message received after successful validation of schema and signature content: application/json: schema: type: object additionalProperties: false properties: catalog: $ref: '#/components/schemas/Catalog'