Add an order or purchase

curl --request POST \
  --url https://api.bonifiq.com.br/v1/pvt/Order \
  --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,
    "EnrolledDate": "2023-11-07T05:31:56Z"
  },
  "Products": [
    {
      "OriginalId": "<string>",
      "Title": "<string>",
      "Url": "<string>",
      "ImageUrl": "<string>",
      "IsActive": true,
      "ProductPrice": 123,
      "ProductBrand": {
        "OriginalId": "<string>",
        "Name": "<string>"
      },
      "ProductCategory": {
        "OriginalId": "<string>",
        "Name": "<string>",
        "Description": "<string>",
        "ParentCategory": "<unknown>"
      }
    }
  ],
  "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>",
      "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"
          }
        ]
      },
      "AffiliateCode": "<string>",
      "AffiliateCodeAssignedAt": "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>",
    "Metadatas": [
      {
        "Id": 123,
        "OrderId": 123,
        "Name": "<string>",
        "Value": "<string>"
      }
    ],
    "EstimatedBonus": {
      "GenerateBonus": true,
      "EstimatedPoints": 123,
      "EstimatedCashback": 123,
      "EstimatedCashbackFormatted": "<string>"
    }
  },
  "Code": "<string>",
  "CodeName": "<string>",
  "HasWarning": true,
  "HasError": true
}

Order

Add an order or purchase

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

Order

Add an order or purchase

curl --request POST \
  --url https://api.bonifiq.com.br/v1/pvt/Order \
  --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,
    "EnrolledDate": "2023-11-07T05:31:56Z"
  },
  "Products": [
    {
      "OriginalId": "<string>",
      "Title": "<string>",
      "Url": "<string>",
      "ImageUrl": "<string>",
      "IsActive": true,
      "ProductPrice": 123,
      "ProductBrand": {
        "OriginalId": "<string>",
        "Name": "<string>"
      },
      "ProductCategory": {
        "OriginalId": "<string>",
        "Name": "<string>",
        "Description": "<string>",
        "ParentCategory": "<unknown>"
      }
    }
  ],
  "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>",
      "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"
          }
        ]
      },
      "AffiliateCode": "<string>",
      "AffiliateCodeAssignedAt": "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>",
    "Metadatas": [
      {
        "Id": 123,
        "OrderId": 123,
        "Name": "<string>",
        "Value": "<string>"
      }
    ],
    "EstimatedBonus": {
      "GenerateBonus": true,
      "EstimatedPoints": 123,
      "EstimatedCashback": 123,
      "EstimatedCashbackFormatted": "<string>"
    }
  },
  "Code": "<string>",
  "CodeName": "<string>",
  "HasWarning": true,
  "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

Products

object[] | null

Products listed on the order.

Show child attributes

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

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

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

SalesPerson

object

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

Show child attributes

ExternalCoupon

string | null

Response

200 - application/json

Standard response envelope used by the External API.

ErrorMessage

string | null

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

Legacy numeric error code derived from internal API errors when available. This field is relevant only for error flows that use ApiResponseErrorDescription.

Result

object

Business payload returned by the endpoint.

Show child attributes

Code

string | null

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

Symbolic enum name associated with Code, such as CheckoutNotFound.

Severity

enum<integer>

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.

Available options:

0,

1,

2

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.

Change the Status of the customer in BonifiQ request for cancelling a purchase order