---
title: "Add an order or purchase"
method: POST
path: "/v1/pvt/Order"
tags: ["Order"]
---

# Add an order or purchase

`POST /v1/pvt/Order`

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

## Request body

- CreateOrderRequest — Purchase Order Model
  - `OriginalId` string — This is the Id in the client store.
  - `OrderPlacementDate` string, date-time — Date of the customer's purchase.
  - `OrderCompletedDate` string, date-time, nullable — Date the order reached the completed state (usually it's invoiced or delivered).
  - `OrderCancelledDate` string, date-time, nullable — if the order is cancelled, contains the date.
  - `OrderStatus` string — Status at the client's order system.
  - `IsCancelledOrReturned` boolean — if true the order was cancelled or returned.
  - `IsCompleted` boolean — If true it means the order has reached its final status and points can be awarded to the consumer.
  - `OrderTotal` number — Can be used at Loyalty Programs. Important: these values should not include Shipping costs.
  - `Customer` ExternalCreateCustomerRequest — Creater Customer body Request
    - `OriginalId` string — This is the Id in the client store.
    - `Name` string — Customer name.
    - `Email` string, nullable — Customer email.
    - `Phone` string, nullable — Customer Contact Phone.
    - `BirthdayDate` string, date-time, nullable — Customer Birthdate.
    - `SignupDate` string, date-time, nullable — Date when the customer made the register on client store.
    - `Document` string, nullable — Some document number from the customer, accepts any string.
    - `IsEnrolled` boolean — If true the customer is participating on the points plan from the store.
    - `EnrolledDate` string, date-time, nullable — Date when the customer made entered into the program. Use the OrderPlacementDate if not informed.
  - `Products` object[], nullable — Products listed on the order.
    - `OriginalId` string — Id from the client store.
    - `Title` string — Product Name
    - `Url` string, nullable — Direct url to the product on the client store.
    - `ImageUrl` string, nullable — Product img url.
    - `IsActive` boolean — if true the product is active on the store.
    - `ProductPrice` number, nullable — 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
    - `ProductBrand` CreateProductBrandRequest
      - `OriginalId` string — Id from the client store
      - `Name` string — Brand Name
    - `ProductCategory` CreateProductCategoryRequest — Product Category model with support for hierarchical categories.
      - `OriginalId` string — Id from the client store
      - `Name` string — Category Name
      - `Description` string, nullable — Category Description
      - `ParentCategory` CreateProductCategoryRequest — recursive
  - `UpdatedDate` string, date-time — the date from the last update on this order.
  - `Coupon` string, nullable — Coupon code used on this order.
  - `Metadatas` object[], nullable — 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.
    - `Name` string
    - `Value` string
  - `PaymentMethod` CreateOrderPaymentMethod
    - `OriginalId` string — 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` string — Name of the payment method used. It could be shown to the customer so it should be meaningful.
    - `PaidAmount` number, nullable — Optional amount paid using this payment method.
  - `PaymentMethods` object[], nullable — Preferred field for the payment methods used in this purchase. Each item should be as specific as possible (ie: instead of using "Credit Card" use "Visa Credit Card" and so on).
    - `OriginalId` string — 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` string — Name of the payment method used. It could be shown to the customer so it should be meaningful.
    - `PaidAmount` number, nullable — Optional amount paid using this payment method.
  - `Branch` CreateOrderBranch
    - `OriginalId` string — This is the Id of the branch (filial, loja, etc) in the client store. Can be any string.
    - `Name` string — This is the name of the branch. Can be any string possible
  - `SalesPerson` CreateOrderSalesPerson
    - `OriginalId` string — This is the Id of the Sales Person. Can be any string or number.
    - `Name` string — This is the name of the sales person. Can be any string.
  - `ExternalCoupon` string, nullable

## Response `200`

- BaseExternalApiResponseOfPrivateOrderCreateResponse — Standard response envelope used by the External API.
  - `ErrorMessage` string, nullable — Error message returned when the request fails validation or processing. For warnings and successful responses, consumers should usually inspect `Result`, `Code` and `Severity` first.
  - `ErrorCode` integer, nullable — Legacy numeric error code derived from internal API errors when available. This field is relevant only for error flows that use `ApiResponseErrorDescription`.
  - `Result` PrivateOrderCreateResponse — This class represents a request with an external Id (such as OrderId) in a third-party system
    - `Id` integer
    - `OriginalId` string — This is the Id in the third party system.
    - `OrderPlacementDate` string, date-time — Date of the customer's purchase.
    - `OrderCompletedDate` string, date-time, nullable — Date the order reached the completed state (usually it's invoiced or delivered).
    - `OrderCancelledDate` string, date-time, nullable — if the order is cancelled, contains the date.
    - `OrderStatus` string — Status at the client's order system.
    - `IsCancelledOrReturned` boolean — if true the order was cancelled or returned.
    - `IsCompleted` boolean — If true it means the order has reached its final status and points can be awarded to the consumer.
    - `OrderTotal` number — Can be used at Loyalty Programs. Important: these values should not include Shipping costs.
    - `Customer` ApiCustomer — This class represents a request with an external Id (such as OrderId) in a third-party system
      - `Id` integer
      - `OriginalId` string — This is the Id in the third party system.
      - `Name` string
      - `Email` string
      - `Phone` string
      - `BirthdayDate` string, date-time, nullable
      - `SignupDate` string, date-time
      - `Document` string
      - `IsEnrolled` boolean
      - `PointsBalance` integer
      - `BalanceOfPoints` integer
      - `Cashback` number, nullable
      - `BirthdayUpdateDate` string, date-time, nullable
      - `FirstName` string
      - `PublicId` string, guid, nullable
      - `SecondaryId` string, nullable
      - `OrderCount` integer, nullable
      - `ReasonEnrolled` string, nullable
      - `AdminId` integer, nullable
      - `EmailAdmin` string, nullable
      - `EnrolledDate` string, date-time, nullable
      - `TierName` string
      - `Origin` 0 | 1 | 2 | 3 | 4 | 5 — 0 = Platform 1 = PDV 2 = API 3 = OfflinePlatform 4 = Admin 5 = Affiliate
      - `RfmGroup` 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 — 0 = CantMiss 1 = ConstantBuyers 2 = Vips 3 = AtRisk 4 = NeedAttention 5 = Promising 6 = Disconnected 7 = Hibernating 8 = Sleepy 9 = OnTheRise 10 = NewCustomers
      - `RfmGroupName` string, nullable
      - `Affiliate` ApiAffiliate
        - `Id` integer
        - `CustomerId` integer
        - `IsActive` boolean
        - `AffiliateCoupon` string, nullable
        - `LastUpdated` string, date-time, nullable
        - `CouponHistories` object[]
          - `Id` integer
          - `AffiliateId` integer
          - `Coupon` string
          - `AssociatedDate` string, date-time
      - `AffiliateCode` string, nullable
      - `AffiliateCodeAssignedAt` string, date-time, nullable
    - `Products` object[], nullable — Products listed on the order.
      - `OriginalId` string — Id from the client store
      - `Title` string — Product Title/Name
      - `Url` string, nullable — Url from the client store from the product.
      - `ImageUrl` string, nullable — Url from where the Product image is hosted.
      - `IsActive` boolean — If true the product is active.
      - `ProductPrice` number, nullable
    - `UpdatedDate` string, date-time — the date from the last update on this order.
    - `Coupon` string, nullable — Coupon code used on this order.
    - `State` 0 | 1 | 2 | 3 | 4 — 0 = Initial 1 = Pending 2 = Completed 3 = Cancelled 4 = Ignored
    - `Origin` 0 | 1 | 2 | 3 | 4 — 0 = Integration 1 = API 2 = Import 3 = PDV 4 = OfflineIntegration
    - `Branch` ApiBranch — This class represents a request with an external Id (such as OrderId) in a third-party system
      - `Id` integer
      - `OriginalId` string — This is the Id in the third party system.
      - `Name` string
    - `TenantSalesman` ApiTenantSalesman — This class represents a request with an external Id (such as OrderId) in a third-party system
      - `Id` integer
      - `OriginalId` string — This is the Id in the third party system.
      - `Name` string
      - `Store` string
      - `Branch` ApiBranch — This class represents a request with an external Id (such as OrderId) in a third-party system
        - `Id` integer
        - `OriginalId` string — This is the Id in the third party system.
        - `Name` string
      - `BranchId` integer, nullable
    - `Metadatas` object[], nullable
      - `Id` integer
      - `OrderId` integer
      - `Name` string
      - `Value` string
    - `ExternalCoupon` string, nullable — This is the "official" field for coupons from the ecomm platform - normally used for affiliate Coupon
    - `EstimatedBonus` OrderEstimatedBonusResponse
      - `GenerateBonus` boolean
      - `EstimatedPoints` integer
      - `EstimatedCashback` number
      - `EstimatedCashbackFormatted` string
  - `Code` string, nullable — 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.
  - `CodeName` string, nullable — Symbolic enum name associated with `Code`, such as `CheckoutNotFound`.
  - `Severity` 0 | 1 | 2 — 0 = Success 1 = Warning 2 = Error
  - `HasWarning` boolean — 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` boolean — 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`.

---

[API](https://skmtc.net/bonifiq/apis/bonifiq-private-apis.md) · [All operations](https://skmtc.net/bonifiq/apis/bonifiq-private-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bonifiq/bonifiq-private-apis/revisions/070a57eeffdc/schema)