This is shortcut for the original /orders endpoint to add orders into BonifiQ

curl --request POST \
  --url https://api.bonifiq.com.br/v1/pvt/POS/orders \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "OriginalId": "<string>",
  "OrderPlacementDate": "2023-11-07T05:31:56Z",
  "OrderCompletedDate": "2023-11-07T05:31:56Z",
  "OrderCancelledDate": "2023-11-07T05:31:56Z",
  "OrderStatus": "<string>",
  "IsCancelledOrReturned": true,
  "IsCompleted": true,
  "OrderTotal": 123,
  "Customer": {
    "OriginalId": "<string>",
    "Name": "<string>",
    "Email": "<string>",
    "Phone": "<string>",
    "BirthdayDate": "2023-11-07T05:31:56Z",
    "SignupDate": "2023-11-07T05:31:56Z",
    "Document": "<string>",
    "IsEnrolled": true
  },
  "Products": [
    {
      "OriginalId": "<string>",
      "Title": "<string>",
      "Url": "<string>",
      "ImageUrl": "<string>",
      "IsActive": true,
      "ProductPrice": 123,
      "ProductBrand": {
        "OriginalId": "<string>",
        "Name": "<string>"
      }
    }
  ],
  "UpdatedDate": "2023-11-07T05:31:56Z",
  "Coupon": "<string>",
  "Metadatas": [
    {
      "Name": "<string>",
      "Value": "<string>"
    }
  ],
  "PaymentMethod": {
    "OriginalId": "<string>",
    "Name": "<string>"
  },
  "Branch": {
    "OriginalId": "<string>",
    "Name": "<string>"
  },
  "SalesPerson": {
    "OriginalId": "<string>",
    "Name": "<string>"
  },
  "ExternalCoupon": "<string>"
}
'

{
  "ErrorMessage": "<string>",
  "ErrorCode": 123,
  "Result": {
    "Id": 123,
    "OriginalId": "<string>",
    "OrderPlacementDate": "2023-11-07T05:31:56Z",
    "OrderCompletedDate": "2023-11-07T05:31:56Z",
    "OrderCancelledDate": "2023-11-07T05:31:56Z",
    "OrderStatus": "<string>",
    "IsCancelledOrReturned": true,
    "IsCompleted": true,
    "OrderTotal": 123,
    "Customer": {
      "Id": 123,
      "OriginalId": "<string>",
      "Name": "<string>",
      "Email": "<string>",
      "Phone": "<string>",
      "BirthdayDate": "2023-11-07T05:31:56Z",
      "SignupDate": "2023-11-07T05:31:56Z",
      "Document": "<string>",
      "IsEnrolled": true,
      "PointsBalance": 123,
      "BalanceOfPoints": 123,
      "Cashback": 123,
      "BirthdayUpdateDate": "2023-11-07T05:31:56Z",
      "FirstName": "<string>",
      "PublicId": "<string>",
      "SecondaryId": "<string>",
      "OrderCount": 123,
      "ReasonEnrolled": "<string>",
      "AdminId": 123,
      "EmailAdmin": "<string>",
      "EnrolledDate": "2023-11-07T05:31:56Z",
      "TierName": "<string>",
      "Origin": 0,
      "RfmGroup": 0,
      "RfmGroupName": "<string>",
      "Affiliate": {
        "Id": 123,
        "CustomerId": 123,
        "IsActive": true,
        "AffiliateCoupon": "<string>",
        "LastUpdated": "2023-11-07T05:31:56Z",
        "CouponHistories": [
          {
            "Id": 123,
            "AffiliateId": 123,
            "Coupon": "<string>",
            "AssociatedDate": "2023-11-07T05:31:56Z"
          }
        ]
      }
    },
    "Products": [
      {
        "OriginalId": "<string>",
        "Title": "<string>",
        "Url": "<string>",
        "ImageUrl": "<string>",
        "IsActive": true,
        "ProductPrice": 123
      }
    ],
    "UpdatedDate": "2023-11-07T05:31:56Z",
    "Coupon": "<string>",
    "State": 0,
    "Origin": 0,
    "Metadatas": [
      {
        "Id": 123,
        "OrderId": 123,
        "Name": "<string>",
        "Value": "<string>"
      }
    ]
  },
  "HasError": true
}

POS

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

POST

pvt

POS

orders

This is shortcut for the original /orders endpoint to add orders into BonifiQ

curl --request POST \
  --url https://api.bonifiq.com.br/v1/pvt/POS/orders \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "OriginalId": "<string>",
  "OrderPlacementDate": "2023-11-07T05:31:56Z",
  "OrderCompletedDate": "2023-11-07T05:31:56Z",
  "OrderCancelledDate": "2023-11-07T05:31:56Z",
  "OrderStatus": "<string>",
  "IsCancelledOrReturned": true,
  "IsCompleted": true,
  "OrderTotal": 123,
  "Customer": {
    "OriginalId": "<string>",
    "Name": "<string>",
    "Email": "<string>",
    "Phone": "<string>",
    "BirthdayDate": "2023-11-07T05:31:56Z",
    "SignupDate": "2023-11-07T05:31:56Z",
    "Document": "<string>",
    "IsEnrolled": true
  },
  "Products": [
    {
      "OriginalId": "<string>",
      "Title": "<string>",
      "Url": "<string>",
      "ImageUrl": "<string>",
      "IsActive": true,
      "ProductPrice": 123,
      "ProductBrand": {
        "OriginalId": "<string>",
        "Name": "<string>"
      }
    }
  ],
  "UpdatedDate": "2023-11-07T05:31:56Z",
  "Coupon": "<string>",
  "Metadatas": [
    {
      "Name": "<string>",
      "Value": "<string>"
    }
  ],
  "PaymentMethod": {
    "OriginalId": "<string>",
    "Name": "<string>"
  },
  "Branch": {
    "OriginalId": "<string>",
    "Name": "<string>"
  },
  "SalesPerson": {
    "OriginalId": "<string>",
    "Name": "<string>"
  },
  "ExternalCoupon": "<string>"
}
'

{
  "ErrorMessage": "<string>",
  "ErrorCode": 123,
  "Result": {
    "Id": 123,
    "OriginalId": "<string>",
    "OrderPlacementDate": "2023-11-07T05:31:56Z",
    "OrderCompletedDate": "2023-11-07T05:31:56Z",
    "OrderCancelledDate": "2023-11-07T05:31:56Z",
    "OrderStatus": "<string>",
    "IsCancelledOrReturned": true,
    "IsCompleted": true,
    "OrderTotal": 123,
    "Customer": {
      "Id": 123,
      "OriginalId": "<string>",
      "Name": "<string>",
      "Email": "<string>",
      "Phone": "<string>",
      "BirthdayDate": "2023-11-07T05:31:56Z",
      "SignupDate": "2023-11-07T05:31:56Z",
      "Document": "<string>",
      "IsEnrolled": true,
      "PointsBalance": 123,
      "BalanceOfPoints": 123,
      "Cashback": 123,
      "BirthdayUpdateDate": "2023-11-07T05:31:56Z",
      "FirstName": "<string>",
      "PublicId": "<string>",
      "SecondaryId": "<string>",
      "OrderCount": 123,
      "ReasonEnrolled": "<string>",
      "AdminId": 123,
      "EmailAdmin": "<string>",
      "EnrolledDate": "2023-11-07T05:31:56Z",
      "TierName": "<string>",
      "Origin": 0,
      "RfmGroup": 0,
      "RfmGroupName": "<string>",
      "Affiliate": {
        "Id": 123,
        "CustomerId": 123,
        "IsActive": true,
        "AffiliateCoupon": "<string>",
        "LastUpdated": "2023-11-07T05:31:56Z",
        "CouponHistories": [
          {
            "Id": 123,
            "AffiliateId": 123,
            "Coupon": "<string>",
            "AssociatedDate": "2023-11-07T05:31:56Z"
          }
        ]
      }
    },
    "Products": [
      {
        "OriginalId": "<string>",
        "Title": "<string>",
        "Url": "<string>",
        "ImageUrl": "<string>",
        "IsActive": true,
        "ProductPrice": 123
      }
    ],
    "UpdatedDate": "2023-11-07T05:31:56Z",
    "Coupon": "<string>",
    "State": 0,
    "Origin": 0,
    "Metadatas": [
      {
        "Id": 123,
        "OrderId": 123,
        "Name": "<string>",
        "Value": "<string>"
      }
    ]
  },
  "HasError": true
}

Authorizations

Authorization

string

header

required

Use API Basic Auth Keys

Body

application/json

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> | null

Date the order reached the completed state (usually it's invoiced or delivered).

OrderCancelledDate

string<date-time> | null

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<decimal>

Can be used at Loyalty Programs. Important: these values should not include Shipping costs.

Customer

object

Buyer registration.

Show child attributes

Customer.OriginalId

string

This is the Id in the client store.

Customer.Name

string

Customer name.

Customer.Email

string | null

Customer email.

Customer.Phone

string | null

Customer Contact Phone.

Customer.BirthdayDate

string<date-time> | null

Customer Birthdate.

Date when the customer made the register on client store.

Customer.Document

string | null

Some document number from the customer, accepts any string.

Customer.IsEnrolled

boolean

If true the customer is participating on the points plan from the store.

Products

object[] | null

Products listed on the order.

Show child attributes

Products.OriginalId

string

Id from the client store.

Products.Title

string

Product Name

Products.Url

string | null

Direct url to the product on the client store.

Products.ImageUrl

string | null

Product img url.

Products.IsActive

boolean

if true the product is active on the store.

Products.ProductPrice

number<decimal> | null

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

Products.ProductBrand

object

Show child attributes

Products.ProductBrand.OriginalId

string

Id from the client store

Products.ProductBrand.Name

string

Brand Name

UpdatedDate

string<date-time>

the date from the last update on this order.

Coupon

string | null

Coupon code used on this order.

Metadatas

object[] | null

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.

Show child attributes

Metadatas.Name

string

Metadatas.Value

string

PaymentMethod

object

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

Show child attributes

PaymentMethod.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

PaymentMethod.Name

string

Name of the payment method used. It could be shown to the customer so it should be meaningful.

Branch

object

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.

Show child attributes

Branch.OriginalId

string

This is the Id of the branch (filial, loja, etc) in the client store. Can be any string.

Branch.Name

string

This is the name of the branch. Can be any string possible

SalesPerson

object

A sales person is the person responsible for the sale. It can be used for filtering reports.

Show child attributes

SalesPerson.OriginalId

string

This is the Id of the Sales Person. Can be any string or number.

SalesPerson.Name

string

This is the name of the sales person. Can be any string.

ExternalCoupon

string | null

Response

200 - application/json

ErrorMessage

string | null

Error message or description

ErrorCode

integer<int32> | null

Optional error code, if available

Result

object

This class represents a request with an external Id (such as OrderId) in a third-party system

Show child attributes

Result.Id

integer<int32>

Result.OriginalId

string

This is the Id in the third party system.

Result.OrderPlacementDate

string<date-time>

Date of the customer's purchase.

Result.OrderCompletedDate

string<date-time> | null

Date the order reached the completed state (usually it's invoiced or delivered).

Result.OrderCancelledDate

string<date-time> | null

if the order is cancelled, contains the date.

Result.OrderStatus

string

Status at the client's order system.

Result.IsCancelledOrReturned

boolean

if true the order was cancelled or returned.

Result.IsCompleted

boolean

If true it means the order has reached its final status and points can be awarded to the consumer.

Result.OrderTotal

number<decimal>

Can be used at Loyalty Programs. Important: these values should not include Shipping costs.

Result.Customer

object

Buyer registration.

Show child attributes

Result.Customer.Id

integer<int32>

Result.Customer.OriginalId

string

This is the Id in the third party system. This is the Id in the third party system.

Result.Customer.Name

string

Result.Customer.Email

string

Result.Customer.Phone

string

Result.Customer.BirthdayDate

string<date-time> | null

Result.Customer.Document

string

Result.Customer.IsEnrolled

boolean

Result.Customer.PointsBalance

integer<int32>

Result.Customer.BalanceOfPoints

integer<int32>

Result.Customer.Cashback

number<decimal> | null

Result.Customer.BirthdayUpdateDate

string<date-time> | null

Result.Customer.FirstName

string

Result.Customer.PublicId

string<guid> | null

Result.Customer.SecondaryId

string | null

Result.Customer.OrderCount

integer<int32> | null

Result.Customer.ReasonEnrolled

string | null

Result.Customer.AdminId

integer<int32> | null

Result.Customer.EmailAdmin

string | null

Result.Customer.EnrolledDate

string<date-time> | null

Result.Customer.TierName

string

Result.Customer.Origin

enum<integer>

0 = Platform 1 = PDV 2 = API 3 = OfflinePlatform 4 = Admin

Available options:

0,

1,

2,

3,

4

Result.Customer.RfmGroup

enum<integer>

0 = CantMiss 1 = ConstantBuyers 2 = Vips 3 = AtRisk 4 = NeedAttention 5 = Promising 6 = Disconnected 7 = Hibernating 8 = Sleepy 9 = OnTheRise 10 = NewCustomers

Available options:

0,

1,

2,

3,

4,

5,

6,

7,

8,

9,

10

Result.Customer.RfmGroupName

string | null

Result.Customer.Affiliate

object

Show child attributes

Result.Customer.Affiliate.Id

integer<int32>

Result.Customer.Affiliate.CustomerId

integer<int32>

Result.Customer.Affiliate.IsActive

boolean

Result.Customer.Affiliate.AffiliateCoupon

string | null

Result.Customer.Affiliate.LastUpdated

string<date-time> | null

Result.Customer.Affiliate.CouponHistories

object[]

Show child attributes

Result.Customer.Affiliate.CouponHistories.Id

integer<int32>

Result.Customer.Affiliate.CouponHistories.AffiliateId

integer<int32>

Result.Customer.Affiliate.CouponHistories.Coupon

string

Result.Customer.Affiliate.CouponHistories.AssociatedDate

string<date-time>

Result.Products

object[] | null

Products listed on the order.

Show child attributes

Result.Products.OriginalId

string

Id from the client store

Result.Products.Title

string

Product Title/Name

Result.Products.Url

string | null

Url from the client store from the product.

Result.Products.ImageUrl

string | null

Url from where the Product image is hosted.

Result.Products.IsActive

boolean

If true the product is active.

Result.Products.ProductPrice

number<decimal> | null

Result.UpdatedDate

string<date-time>

the date from the last update on this order.

Result.Coupon

string | null

Coupon code used on this order.

Result.State

enum<integer>

Order State: 0=Inicial, 1= Pendente, 2=Completo, 3=Cancelado, 4=Ignorado

Available options:

0,

1,

2,

3,

4

Result.Origin

enum<integer>

How this order was integrated into BonifiQ 0 = Order Integration with ecommerce platform 1 = External API 2 = File import

Available options:

0,

1,

2,

3,

4

Result.Metadatas

object[] | null

Show child attributes

Result.Metadatas.Id

integer<int32>

Result.Metadatas.OrderId

integer<int32>

Result.Metadatas.Name

string

Result.Metadatas.Value

string

HasError

boolean

If true the request had an error.

Cancel an existing reward. By canceling the customer will have their points back. The reward will be in the canceled state.This is shortcut for the original /orders/cancel endpoint for canceling orders.

⌘I

API Privada

API Pública

Endpoint Examples

This is shortcut for the original /orders endpoint to add orders into BonifiQ

Order State

Order Status

Order Total

Coupon

Authorizations

Body

Response