> ## Documentation Index > Fetch the complete documentation index at: https://developers.bonifiq.com.br/llms.txt > Use this file to discover all available pages before exploring further. # This is shortcut for the original /orders endpoint to add orders into BonifiQ > An important part of the program points is awarding point for purchases that customers made. In order for points to be given we need to receive purchases that the customers made. ## Order State In BonifiQ an order can be in one of these 3 states: - Completed: An order in a completed state will receive points according to the configuration in BonifiQ panel - Canceled: An order that is incomplete, not paide or returned. If any points was awarded they will be removed - Pending: An order that is neither Completed nor Canceled. You dont need to send `pending` orders to BonifiQ. You can send them when they are completed (or canceled). The pending state exists for integrations that requires this flow. To set the State of the order use the `IsCompleted` and `IsCancelledOrReturned` fields. Whenever one of them is `true` the respective `OrderCompletedDate` or `OrderCancelledDate` must be set. ## Order Status The `OrderStatus` field is the status in the platform. This is merely informative ## Order Total This is a very important field as it determines how many points the user will be awarded. This value must not consider shipping costs, taxes, discounts, promotions, giftcard, etc In other words, the value must be what the customer really paid discounted shipping ## Coupon The Coupon field is important as is the way BonifiQ is aware of an used coupon or reward. Use this field as follow: - If this order used a reward from the `Redeem` endpoint, them pass here the `ExternalCode` return from the redeem api call - If this order didt not used an reward from BonifiQ pass here the coupon used by the customer, if available ## OpenAPI ````yaml https://api.bonifiq.com.br/swagger/Private%20APIs/swagger.json post /v1/pvt/POS/orders openapi: 3.0.0 info: title: BonifiQ Private APIs description: >- # Introduction This is the BonifiQ Private APIs documentation. With these endpoints you can interact with BonifiQ systems and enhance your program points. # Limitations These endpoints are intended to be used in backend communication so they are not CORS-compatible and cannot be used by in-browser frontend libraries (such as React, Angular, Vue, jQuery, etc) If are required to call BonifiQ API from a browser, please refer to our [Public APIs](https://api.bonifiq.com.br/apidocs/public) # Authentication These Private APis use the [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) scheme. You need both an API Token (Username) and API Key (Password) to use with it You can generate this key pair in BonifiQ admin panel, at the "API Keys" menu. # How to use this page ## Making calls You can simulate, test and make calls to API from this Swagger page. To do that: - Click on the **Authorize** button - Inform the Username (API Token) and Passwoird (API Key) and click on **Authorize** - From the list bellow, choose an API call and click on **Try it out** - Inform the required parameters (if any) and click on **Execute** ## Verifying requests and responses bodies In every API Call there is an explanation of what each field means, theirs types and accepted values for all Requests and Responses. To view this information, just go to any API Call bellow and in the Responses section, click on the Schema. version: 1.0.0 servers: - url: https://api.bonifiq.com.br security: [] tags: - name: POS description: >- Flow methods to integrate BonifiQ with a POS system. Check the Flow Documentation link on the right externalDocs: description: Flow Documentation url: >- https://suporte.bonifiq.com.br/support/solutions/articles/159000319538-integrar-com-pdv - name: Checkout description: Operations related to checkout cashback redeem, refresh and removal - name: Customization description: Retrieve customizations for the loyalty program - name: Rewards description: Interact with rewards already redeemed paths: /v1/pvt/POS/orders: post: tags: - POS summary: >- This is shortcut for the original /orders endpoint to add orders into BonifiQ description: >- An important part of the program points is awarding point for purchases that customers made. In order for points to be given we need to receive purchases that the customers made. ## Order State In BonifiQ an order can be in one of these 3 states: - Completed: An order in a completed state will receive points according to the configuration in BonifiQ panel - Canceled: An order that is incomplete, not paide or returned. If any points was awarded they will be removed - Pending: An order that is neither Completed nor Canceled. You dont need to send `pending` orders to BonifiQ. You can send them when they are completed (or canceled). The pending state exists for integrations that requires this flow. To set the State of the order use the `IsCompleted` and `IsCancelledOrReturned` fields. Whenever one of them is `true` the respective `OrderCompletedDate` or `OrderCancelledDate` must be set. ## Order Status The `OrderStatus` field is the status in the platform. This is merely informative ## Order Total This is a very important field as it determines how many points the user will be awarded. This value must not consider shipping costs, taxes, discounts, promotions, giftcard, etc In other words, the value must be what the customer really paid discounted shipping ## Coupon The Coupon field is important as is the way BonifiQ is aware of an used coupon or reward. Use this field as follow: - If this order used a reward from the `Redeem` endpoint, them pass here the `ExternalCode` return from the redeem api call - If this order didt not used an reward from BonifiQ pass here the coupon used by the customer, if available operationId: POS_NewOrder requestBody: x-name: orderData content: application/json: schema: $ref: '#/components/schemas/CreateOrderRequest' required: true x-position: 1 responses: '200': description: '' content: application/json: schema: $ref: >- #/components/schemas/BaseExternalApiResponseOfPrivateOrderCreateResponse security: - Basic Authentication: [] components: schemas: CreateOrderRequest: type: object description: Purchase Order Model additionalProperties: false properties: OriginalId: type: string description: 'This is the Id in the client store. ' OrderPlacementDate: type: string description: 'Date of the customer''s purchase. ' format: date-time OrderCompletedDate: type: string description: >- Date the order reached the completed state (usually it's invoiced or delivered). format: date-time nullable: true OrderCancelledDate: type: string description: if the order is cancelled, contains the date. format: date-time nullable: true OrderStatus: type: string description: Status at the client's order system. IsCancelledOrReturned: type: boolean description: if true the order was cancelled or returned. IsCompleted: type: boolean description: >- If true it means the order has reached its final status and points can be awarded to the consumer. OrderTotal: type: number description: >- Can be used at Loyalty Programs. Important: these values should not include Shipping costs. format: decimal Customer: description: Buyer registration. oneOf: - $ref: '#/components/schemas/ExternalCreateCustomerRequest' Products: type: array description: Products listed on the order. nullable: true xml: wrapped: true items: xml: name: CreateProductRequest oneOf: - $ref: '#/components/schemas/CreateProductRequest' UpdatedDate: type: string description: the date from the last update on this order. format: date-time Coupon: type: string description: Coupon code used on this order. nullable: true Metadatas: type: array description: >- This is a key-value list of extra information regarding the order. It could be informative only or being part of an business rule to be used later. nullable: true xml: wrapped: true items: xml: name: CreateOrderRequestMetadata oneOf: - $ref: '#/components/schemas/CreateOrderRequestMetadata' PaymentMethod: description: >- The Payment Method used in this purchase. Should be the more specific as possible (ie: instead of using "Credit Card" use "Visa Credit Card" and so on). This field can be used later on to create extra points purchase rules nullable: true oneOf: - $ref: '#/components/schemas/CreateOrderPaymentMethod' Branch: description: >- A Branch is physical location or outlet of a store (loja, filial, etc). This is used to receive information of which store the purchase was made. It can be later used to create rules for points or filtering reports. nullable: true oneOf: - $ref: '#/components/schemas/CreateOrderBranch' SalesPerson: description: >- A sales person is the person responsible for the sale. It can be used for filtering reports. nullable: true oneOf: - $ref: '#/components/schemas/CreateOrderSalesPerson' ExternalCoupon: type: string nullable: true BaseExternalApiResponseOfPrivateOrderCreateResponse: type: object description: Standard response envelope used by the External API. additionalProperties: false properties: ErrorMessage: type: string description: >- Error message returned when the request fails validation or processing. For warnings and successful responses, consumers should usually inspect `Result`, `Code` and `Severity` first. nullable: true ErrorCode: type: integer description: >- Legacy numeric error code derived from internal API errors when available. This field is relevant only for error flows that use `ApiResponseErrorDescription`. format: int32 nullable: true Result: description: Business payload returned by the endpoint. nullable: true oneOf: - $ref: '#/components/schemas/PrivateOrderCreateResponse' Code: type: string description: >- Endpoint-specific business code formatted as a two-digit string, such as `03` or `07`. This field is available for success, warning and error outcomes. nullable: true CodeName: type: string description: >- Symbolic enum name associated with `Code`, such as `CheckoutNotFound`. nullable: true Severity: description: >- Final severity of the response. `Success` means the action completed as expected, `Warning` means the request was valid but the business outcome is informational or non-ideal, and `Error` means the request should be treated as a failure. oneOf: - $ref: '#/components/schemas/ExternalApiResponseSeverity' HasWarning: type: boolean description: >- Convenience flag that is `true` when `Severity` is `Warning`. Warnings are valid `200 OK` business outcomes and should not be handled as transport or validation errors. HasError: type: boolean description: >- Indicates whether the request failed and should be handled as an error response. This flag is reserved for real API errors; warnings must keep this property as `false`. ExternalCreateCustomerRequest: type: object description: Creater Customer body Request additionalProperties: false properties: OriginalId: type: string description: 'This is the Id in the client store. ' Name: type: string description: Customer name. Email: type: string description: Customer email. nullable: true Phone: type: string description: Customer Contact Phone. nullable: true BirthdayDate: type: string description: Customer Birthdate. format: date-time nullable: true SignupDate: type: string description: Date when the customer made the register on client store. format: date-time nullable: true Document: type: string description: Some document number from the customer, accepts any string. nullable: true IsEnrolled: type: boolean description: >- If true the customer is participating on the points plan from the store. EnrolledDate: type: string description: >- Date when the customer made entered into the program. Use the OrderPlacementDate if not informed. format: date-time nullable: true CreateProductRequest: type: object description: Product model. additionalProperties: false properties: OriginalId: type: string description: Id from the client store. Title: type: string description: Product Name Url: type: string description: Direct url to the product on the client store. nullable: true ImageUrl: type: string description: Product img url. nullable: true IsActive: type: boolean description: if true the product is active on the store. ProductPrice: type: number description: >- How much the customer paid for this product. If it is not null and not zero it can be used with extra points for products rule format: decimal nullable: true ProductBrand: description: Product Brand nullable: true oneOf: - $ref: '#/components/schemas/CreateProductBrandRequest' ProductCategory: description: >- Product Category. Supports hierarchical categories with parent references. nullable: true oneOf: - $ref: '#/components/schemas/CreateProductCategoryRequest' CreateOrderRequestMetadata: type: object additionalProperties: false properties: Name: type: string Value: type: string CreateOrderPaymentMethod: type: object additionalProperties: false properties: OriginalId: type: string description: >- The If of the Payment method. Can be any string unique to this Payment Method. If no Id is available you can used the Payment Method Name as Id Name: type: string description: >- Name of the payment method used. It could be shown to the customer so it should be meaningful. CreateOrderBranch: type: object additionalProperties: false properties: OriginalId: type: string description: >- This is the Id of the branch (filial, loja, etc) in the client store. Can be any string. Name: type: string description: This is the name of the branch. Can be any string possible CreateOrderSalesPerson: type: object additionalProperties: false properties: OriginalId: type: string description: This is the Id of the Sales Person. Can be any string or number. Name: type: string description: This is the name of the sales person. Can be any string. PrivateOrderCreateResponse: allOf: - $ref: '#/components/schemas/OrderCreateResponse' - type: object additionalProperties: false properties: EstimatedBonus: $ref: '#/components/schemas/OrderEstimatedBonusResponse' ExternalApiResponseSeverity: type: integer description: |- 0 = Success 1 = Warning 2 = Error x-enumNames: - Success - Warning - Error enum: - 0 - 1 - 2 CreateProductBrandRequest: type: object additionalProperties: false properties: OriginalId: type: string description: Id from the client store Name: type: string description: Brand Name CreateProductCategoryRequest: type: object description: Product Category model with support for hierarchical categories. additionalProperties: false properties: OriginalId: type: string description: Id from the client store Name: type: string description: Category Name Description: type: string description: Category Description nullable: true ParentCategory: description: |- Parent Category. Use this to create a category tree. For example, if you have Electronics > Smartphones > Android, the Android category would have Smartphones as its ParentCategory, and Smartphones would have Electronics as its ParentCategory. nullable: true oneOf: - $ref: '#/components/schemas/CreateProductCategoryRequest' OrderCreateResponse: allOf: - $ref: '#/components/schemas/BaseOriginalIdApiEntity' - type: object additionalProperties: false properties: OrderPlacementDate: type: string description: 'Date of the customer''s purchase. ' format: date-time OrderCompletedDate: type: string description: >- Date the order reached the completed state (usually it's invoiced or delivered). format: date-time nullable: true OrderCancelledDate: type: string description: if the order is cancelled, contains the date. format: date-time nullable: true OrderStatus: type: string description: Status at the client's order system. IsCancelledOrReturned: type: boolean description: if true the order was cancelled or returned. IsCompleted: type: boolean description: >- If true it means the order has reached its final status and points can be awarded to the consumer. OrderTotal: type: number description: >- Can be used at Loyalty Programs. Important: these values should not include Shipping costs. format: decimal Customer: description: Buyer registration. oneOf: - $ref: '#/components/schemas/ApiCustomer' Products: type: array description: Products listed on the order. nullable: true xml: wrapped: true items: xml: name: CreateProductResponse oneOf: - $ref: '#/components/schemas/CreateProductResponse' UpdatedDate: type: string description: the date from the last update on this order. format: date-time Coupon: type: string description: Coupon code used on this order. nullable: true State: description: >- Order State: 0=Inicial, 1= Pendente, 2=Completo, 3=Cancelado, 4=Ignorado oneOf: - $ref: '#/components/schemas/OrderState' Origin: description: |- How this order was integrated into BonifiQ 0 = Order Integration with ecommerce platform 1 = External API 2 = File import oneOf: - $ref: '#/components/schemas/OrderOrigin' Metadatas: type: array nullable: true xml: wrapped: true items: xml: name: ApiOrderMetadata oneOf: - $ref: '#/components/schemas/ApiOrderMetadata' OrderEstimatedBonusResponse: type: object additionalProperties: false properties: GenerateBonus: type: boolean EstimatedPoints: type: integer format: int32 EstimatedCashback: type: number format: decimal EstimatedCashbackFormatted: type: string BaseOriginalIdApiEntity: allOf: - $ref: '#/components/schemas/BaseApiEntity' - type: object description: >- This class represents a request with an external Id (such as OrderId) in a third-party system x-abstract: true additionalProperties: false properties: OriginalId: type: string description: 'This is the Id in the third party system. ' ApiCustomer: allOf: - $ref: '#/components/schemas/BaseOriginalIdApiEntity' - type: object additionalProperties: false properties: Name: type: string Email: type: string Phone: type: string BirthdayDate: type: string format: date-time nullable: true SignupDate: type: string format: date-time Document: type: string IsEnrolled: type: boolean PointsBalance: type: integer format: int32 BalanceOfPoints: type: integer format: int32 Cashback: type: number format: decimal nullable: true BirthdayUpdateDate: type: string format: date-time nullable: true FirstName: type: string PublicId: type: string format: guid nullable: true SecondaryId: type: string nullable: true OrderCount: type: integer format: int32 nullable: true ReasonEnrolled: type: string nullable: true AdminId: type: integer format: int32 nullable: true EmailAdmin: type: string nullable: true EnrolledDate: type: string format: date-time nullable: true TierName: type: string Origin: nullable: true oneOf: - $ref: '#/components/schemas/CustomerOrigin' RfmGroup: nullable: true oneOf: - $ref: '#/components/schemas/MatrizRFMItem' RfmGroupName: type: string nullable: true Affiliate: nullable: true oneOf: - $ref: '#/components/schemas/ApiAffiliate' AffiliateCode: type: string nullable: true AffiliateCodeAssignedAt: type: string format: date-time nullable: true CreateProductResponse: type: object description: Create Product Response model additionalProperties: false properties: OriginalId: type: string description: Id from the client store Title: type: string description: Product Title/Name Url: type: string description: Url from the client store from the product. nullable: true ImageUrl: type: string description: Url from where the Product image is hosted. nullable: true IsActive: type: boolean description: If true the product is active. ProductPrice: type: number format: decimal nullable: true OrderState: type: integer description: |- 0 = Initial 1 = Pending 2 = Completed 3 = Cancelled 4 = Ignored x-enumNames: - Initial - Pending - Completed - Cancelled - Ignored enum: - 0 - 1 - 2 - 3 - 4 OrderOrigin: type: integer description: |- 0 = Integration 1 = API 2 = Import 3 = PDV 4 = OfflineIntegration x-enumNames: - Integration - API - Import - PDV - OfflineIntegration enum: - 0 - 1 - 2 - 3 - 4 ApiOrderMetadata: allOf: - $ref: '#/components/schemas/BaseApiEntity' - type: object additionalProperties: false properties: OrderId: type: integer format: int32 Name: type: string Value: type: string BaseApiEntity: type: object x-abstract: true additionalProperties: false properties: Id: type: integer format: int32 CustomerOrigin: type: integer description: |- 0 = Platform 1 = PDV 2 = API 3 = OfflinePlatform 4 = Admin 5 = Affiliate x-enumNames: - Platform - PDV - API - OfflinePlatform - Admin - Affiliate enum: - 0 - 1 - 2 - 3 - 4 - 5 MatrizRFMItem: type: integer description: |- 0 = CantMiss 1 = ConstantBuyers 2 = Vips 3 = AtRisk 4 = NeedAttention 5 = Promising 6 = Disconnected 7 = Hibernating 8 = Sleepy 9 = OnTheRise 10 = NewCustomers x-enumNames: - CantMiss - ConstantBuyers - Vips - AtRisk - NeedAttention - Promising - Disconnected - Hibernating - Sleepy - OnTheRise - NewCustomers enum: - 0 - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 - 9 - 10 ApiAffiliate: allOf: - $ref: '#/components/schemas/BaseApiEntity' - type: object additionalProperties: false properties: CustomerId: type: integer format: int32 IsActive: type: boolean AffiliateCoupon: type: string nullable: true LastUpdated: type: string format: date-time nullable: true CouponHistories: type: array xml: wrapped: true items: xml: name: ApiAffiliateCouponHistory oneOf: - $ref: '#/components/schemas/ApiAffiliateCouponHistory' ApiAffiliateCouponHistory: allOf: - $ref: '#/components/schemas/BaseApiEntity' - type: object additionalProperties: false properties: AffiliateId: type: integer format: int32 Coupon: type: string AssociatedDate: type: string format: date-time securitySchemes: Basic Authentication: type: http description: Use API Basic Auth Keys name: Basic Authentication in: header scheme: basic ````