Sales submission

Before you start

To send a request to our API, you will need an API credential. To get one, access your Utmify account and follow the path:

Integrations → Webhooks → API Credentials → Add Credential → Create Credential

1. Request Format

1.1 Endpoint

POST https://api.utmify.com.br/api-credentials/orders

1.2 Headers

{
  "x-api-token": "string"
}

1.3 Payload

1.3.1 Body

{
  "orderId": "string",
  "platform": "string",
  "paymentMethod": "credit_card" | "boleto" | "pix" | "paypal" | "free_price",
  "status": "waiting_payment" | "paid" | "refused" | "refunded" | "chargedback",
  "createdAt": "YYYY-MM-DD HH:MM:SS", // UTC
  "approvedDate": "YYYY-MM-DD HH:MM:SS" | null, // UTC
  "refundedAt": "YYYY-MM-DD HH:MM:SS" | null, // UTC
  "customer": Customer,
  "products": Product[],
  "trackingParameters": TrackingParameters,
  "commission": Commission,
  "isTest?": boolean
}

Objects: Customer · Product · TrackingParameters · Commission

1.3.2 Customer

{
  "name": "string",
  "email": "string",
  "phone": "string" | null,
  "document": "string" | null,
  "country?": "string", // ISO 3166-1 alpha-2
  "ip?": "string"
}

1.3.3 Product

{
  "id": "string",
  "name": "string",
  "planId": "string" | null,
  "planName": "string" | null,
  "quantity": number,
  "priceInCents": number
}

1.3.4 TrackingParameters

{
  "src": "string" | null,
  "sck": "string" | null,
  "utm_source": "string" | null,
  "utm_campaign": "string" | null,
  "utm_medium": "string" | null,
  "utm_content": "string" | null,
  "utm_term": "string" | null
}

1.3.5 Commission

{
  "totalPriceInCents": number,
  "gatewayFeeInCents": number,
  "userCommissionInCents": number,
  "currency?": "BRL" | "USD" | "EUR" | "GBP" | "ARS" | "CAD" | "COP" | "MXN" | "PYG" | "CLP" | "PEN" | "PLN"
}

2. Parameter Description

2.1 Headers

Parameter	Example	Description
x-api-token	”KVRxalfMiBfm8Rm1nP5YxfwYzArNsA0VLeWC”	API credential generated in the Utmify Dashboard. This token is used to identify the client and the dashboard that will receive the order.

2.2 Body

Parameter	Example	Description
orderId	”FC72D9AK9”	Order identification on the sales platform.
platform	”GlobalPay”	Name of the platform integrating with Utmify. Recommended in PascalCase.
paymentMethod	”credit_card”	Payment method used in the transaction.
status	”paid”	Payment status of the transaction.
createdAt	”2024-07-25 15:34:14”	Date the order was created (UTC). Must always be the same date when the order status is updated. Note: only orders up to 7 days old are accepted, and up to 45 days for refunds or chargebacks. Non-compliance may result in blocking.
approvedDate	”2024-07-25 15:41:12”	Date the payment was completed (UTC). If the order has not been paid yet, send null.
refundedAt	null	Date the order was refunded (UTC). If not refunded, send null.
customer	Customer	Information about the customer who made the purchase.
products	Array of Product	Information about the products in the transaction.
trackingParameters	TrackingParameters	URL parameters extracted from the checkout URL at the time of purchase and sent to Utmify via Webhook.
commission	Commission	Transaction values.
isTest	false	Defines whether the request is a test. If true, validation will be performed normally, but the transaction will not be saved. To save the order, do not send this field or set it to false.

2.3 Customer

Parameter	Example	Description
name	”Lucas Sampaio”	Customer’s name.
email	”[email protected]”	Customer’s email.
phone	”11991560063”	Customer’s phone number.
document	”43887057481”	Customer’s CPF or CNPJ.
country	”BR”	Customer’s country in ISO 3166-1 alpha-2 format. Not required.
ip	”204.97.192.73”	Customer’s IP address. Not required, but recommended for better sales tracking.

2.4 Product

Parameter	Example	Description
id	”FGC1375Z5”	Product identification.
name	”Pants”	Product name.
planId	”FTS7743C3”	Plan ID (if the platform offers multiple plans for the same product). If not available, send null.
planName	”Christmas Promotion”	Plan name. If not available, send null.
quantity	2	Quantity purchased.
priceInCents	11990	Product price on the sales platform.

2.5 TrackingParameters

Parameter	Example	Description
src	null	Value of src extracted from the checkout URL. If not available, send null.
sck	null	Value of sck extracted from the checkout URL. If not available, send null.
utm_source	”FB”	Value of utm_source extracted from the checkout URL. If not available, send null.
utm_campaign	”Sales 2024/07/10”	Value of utm_campaign extracted from the checkout URL. If not available, send null.
utm_medium	”ABO”	Value of utm_medium extracted from the checkout URL. If not available, send null.
utm_content	”VIDEO 01”	Value of utm_content extracted from the checkout URL. If not available, send null.
utm_term	”Instagram_Reels”	Value of utm_term extracted from the checkout URL. If not available, send null.

2.6 Commission

Parameter	Example	Description
totalPriceInCents	14990	Total transaction value in cents.
gatewayFeeInCents	1500	Amount received by the platform in cents.
userCommissionInCents	13490	Amount received by the seller in cents. This value cannot be 0, unless the user truly received nothing from the sale. If the platform does not want to inform the user commission (not recommended), set this value equal to totalPriceInCents.
currency	”USD”	Purchase currency. If in BRL, this field is not required.

3. Practical Request Examples

3.1 PIX Generated and Paid

A customer placed a PIX order at GlobalPay store through the checkout. The product purchased was a motor oil for $80.00 with $20.00 shipping. The platform charges $1.00 per paid PIX + 3% of the order value. The PIX was generated on 07/26/2024 at 11:35:13 and paid on 07/26/2024 at 11:43:37 (Brasilia time).

3.1.1 PIX Generated

POST https://api.utmify.com.br/api-credentials/orders
Headers: { "x-api-token": "KVRxalfMiBfm8Rm1nP5YxfwYzArNsA0VLeWC" }

{
  "orderId": "8e40b27e-0118-4699-8587-e892beedb403",
  "platform": "GlobalPay",
  "paymentMethod": "pix",
  "status": "waiting_payment",
  "createdAt": "2024-07-26 14:35:13",
  "approvedDate": null,
  "refundedAt": null,
  "customer": {
    "name": "Marcos Goncalves Rodrigues",
    "email": "[email protected]",
    "phone": "19936387209",
    "document": "29672656599",
    "country": "BR",
    "ip": "61.145.134.105"
  },
  "products": [
    {
      "id": "53d5ce96-a548-4c7b-a0bc-da8bfa0f9294",
      "name": "Motor Oil",
      "planId": null,
      "planName": null,
      "quantity": 1,
      "priceInCents": 8000
    }
  ],
  "trackingParameters": {
    "src": null,
    "sck": null,
    "utm_source": "FB",
    "utm_campaign": "CAMPANHA_2|413591587909524",
    "utm_medium": "CONJUNTO_2|498046723566488",
    "utm_content": "ANUNCIO_2|504346051220592",
    "utm_term": "Instagram_Feed"
  },
  "commission": {
    "totalPriceInCents": 10000,
    "gatewayFeeInCents": 400,
    "userCommissionInCents": 9600
  },
  "isTest": false
}

3.1.2 PIX Paid

POST https://api.utmify.com.br/api-credentials/orders
Headers: { "x-api-token": "KVRxalfMiBfm8Rm1nP5YxfwYzArNsA0VLeWC" }

{
  "orderId": "8e40b27e-0118-4699-8587-e892beedb403",
  "platform": "GlobalPay",
  "paymentMethod": "pix",
  "status": "paid",
  "createdAt": "2024-07-26 14:35:13",
  "approvedDate": "2024-07-26 14:43:37",
  "refundedAt": null,
  "customer": {
    "name": "Marcos Goncalves Rodrigues",
    "email": "[email protected]",
    "phone": "19936387209",
    "document": "29672656599",
    "country": "BR",
    "ip": "61.145.134.105"
  },
  "products": [
    {
      "id": "53d5ce96-a548-4c7b-a0bc-da8bfa0f9294",
      "name": "Motor Oil",
      "planId": null,
      "planName": null,
      "quantity": 1,
      "priceInCents": 8000
    }
  ],
  "trackingParameters": {
    "src": null,
    "sck": null,
    "utm_source": "FB",
    "utm_campaign": "CAMPANHA_2|413591587909524",
    "utm_medium": "CONJUNTO_2|498046723566488",
    "utm_content": "ANUNCIO_2|504346051220592",
    "utm_term": "Instagram_Feed"
  },
  "commission": {
    "totalPriceInCents": 10000,
    "gatewayFeeInCents": 400,
    "userCommissionInCents": 9600
  },
  "isTest": false
}

3.2 Credit Card Paid and Refunded

A customer placed a credit card order on 07/15/2024 at 10:30:14 and requested a refund on 07/18/2024 at 22:44:39 (Brasilia time). The order was placed on the GlobalPay platform in dollars, containing a t-shirt for $35.00 and pants for $40.00. The platform charges a 5% fee per order.

3.2.1 Card Paid

POST https://api.utmify.com.br/api-credentials/orders
Headers: { "x-api-token": "JHTbglkQnUhz7Tk2oQ4ZyuVYxBsOpC1XNdYD" }

{
  "orderId": "b101ea20-72c7-473d-bcc4-416fe4d8f3be",
  "platform": "GlobalPay",
  "paymentMethod": "credit_card",
  "status": "paid",
  "createdAt": "2024-07-15 13:30:14",
  "approvedDate": "2024-07-15 13:30:14",
  "refundedAt": null,
  "customer": {
    "name": "Lucas Pereira Barros",
    "email": "[email protected]",
    "phone": "21996972147",
    "document": "24883871428",
    "country": "US",
    "ip": "242.53.157.167"
  },
  "products": [
    {
      "id": "ab341a39-52e1-4dda-92c8-ef336f2bb43c",
      "name": "T-shirt",
      "planId": "e7c5e019-3ac8-4ba1-9a11-2fcb4a4a598d",
      "planName": "Winter T-shirts",
      "quantity": 1,
      "priceInCents": 3500
    },
    {
      "id": "8d7eb04c-ee5c-4c51-b0dc-1bf104d3a37e",
      "name": "Pants",
      "planId": "49436d63-d345-4303-b4fd-f7da003e1a65",
      "planName": "Winter Pants",
      "quantity": 1,
      "priceInCents": 4000
    }
  ],
  "trackingParameters": {
    "src": null,
    "sck": null,
    "utm_source": "FB",
    "utm_campaign": "CAMPANHA_5|761832537749495",
    "utm_medium": "CONJUNTO_5|636393136432792",
    "utm_content": "ANUNCIO_5|525916699209785",
    "utm_term": "Facebook_Mobile_Feed"
  },
  "commission": {
    "totalPriceInCents": 7500,
    "gatewayFeeInCents": 375,
    "userCommissionInCents": 7125,
    "currency": "USD"
  },
  "isTest": false
}

3.2.2 Card Refunded

POST https://api.utmify.com.br/api-credentials/orders
Headers: { "x-api-token": "JHTbglkQnUhz7Tk2oQ4ZyuVYxBsOpC1XNdYD" }

{
  "orderId": "b101ea20-72c7-473d-bcc4-416fe4d8f3be",
  "platform": "GlobalPay",
  "paymentMethod": "credit_card",
  "status": "refunded",
  "createdAt": "2024-07-15 13:30:14",
  "approvedDate": "2024-07-15 13:30:14",
  "refundedAt": "2024-07-19 01:44:39",
  "customer": {
    "name": "Lucas Pereira Barros",
    "email": "[email protected]",
    "phone": "21996972147",
    "document": "24883871428",
    "country": "US",
    "ip": "242.53.157.167"
  },
  "products": [
    {
      "id": "ab341a39-52e1-4dda-92c8-ef336f2bb43c",
      "name": "T-shirt",
      "planId": "e7c5e019-3ac8-4ba1-9a11-2fcb4a4a598d",
      "planName": "Winter T-shirts",
      "quantity": 1,
      "priceInCents": 3500
    },
    {
      "id": "8d7eb04c-ee5c-4c51-b0dc-1bf104d3a37e",
      "name": "Pants",
      "planId": "49436d63-d345-4303-b4fd-f7da003e1a65",
      "planName": "Winter Pants",
      "quantity": 1,
      "priceInCents": 4000
    }
  ],
  "trackingParameters": {
    "src": null,
    "sck": null,
    "utm_source": "FB",
    "utm_campaign": "CAMPANHA_5|761832537749495",
    "utm_medium": "CONJUNTO_5|636393136432792",
    "utm_content": "ANUNCIO_5|525916699209785",
    "utm_term": "Facebook_Mobile_Feed"
  },
  "commission": {
    "totalPriceInCents": 7500,
    "gatewayFeeInCents": 375,
    "userCommissionInCents": 7125,
    "currency": "USD"
  },
  "isTest": false
}

4. Frequently Asked Questions

How do I access Utmify and set up the integration?

Just create a free account at: https://app.utmify.com.br/register

How do I know if the information I sent is correct?

Our API validates all data sent in the payload. Invalid fields and accepted formats will be returned in the request response.

How do I know if the orders I sent were saved correctly?

Access the account used to obtain the credential and navigate to the “Summary” tab. There you will find information about the orders saved on the platform, with filters by specific periods.

I received the error API_CREDENTIAL_NOT_FOUND. What does it mean?

This error indicates that the API Credential was not provided or was passed incorrectly through the request headers. Please refer to the Request Format section for more details.

​Before you start

​1. Request Format

​1.1 Endpoint

​1.2 Headers

​1.3 Payload

​1.3.1 Body

​1.3.2 Customer

​1.3.3 Product

​1.3.4 TrackingParameters

​1.3.5 Commission

​2. Parameter Description

​2.1 Headers

​2.2 Body

​2.3 Customer

​2.4 Product

​2.5 TrackingParameters

​2.6 Commission

​3. Practical Request Examples

​3.1 PIX Generated and Paid

​3.1.1 PIX Generated

​3.1.2 PIX Paid

​3.2 Credit Card Paid and Refunded

​3.2.1 Card Paid

​3.2.2 Card Refunded

​4. Frequently Asked Questions