Skip to main content
Unbox is an e-commerce platform for direct-to-consumer brands, and Unbox Pay is its payment gateway (card, Pix and boleto). This connector brings the orders of your Unbox store with their Unbox Pay payments: amount charged, payment method, status, the moment each payment was confirmed, refunds and chargebacks, the transaction id and the buyer’s CPF or CNPJ. It is useful for reconciling the payments received with your ERP or accounting system (for example, marking receivables as received in Conta Azul). It also brings the items of each order, your payment links and your subscriptions.
The connector only reads data. It never creates orders, payment links or charges in your Unbox store.
The Unbox Partner API does not expose Unbox Pay fees, net amounts, release (credit) dates or transfers. Amounts are the gross amounts charged to the buyer. Fees, net amounts and release dates are only available in the Unbox Pay dashboard.

​
Configuring Unbox Pay as a Source

In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the Unbox Pay option from the list of connectors. Click Next and you’ll be prompted to add your access.

​
1. Add account access

The connector uses the Unbox Partner API. Its credentials are not generated in the Unbox panel: ask your Unbox contact (or Unbox support at ola@unbox.com.br) for access to the Partner API for your store. Unbox provides an API key and a username and password of a partner account linked to your store. The following configurations are available:
  • API Key: The Partner API key (sent as x-api-key) provided by Unbox.
  • Username: The username of the partner account of your store.
  • Password: The password of that partner account.
  • Start Date: (Optional) The earliest order creation date to extract. Leave it empty to extract every order of your store.
  • Lookback Days: (Optional, default 30) On every sync, the orders created in this many days before the last synced order are read again. Unbox only lets the connector search orders by creation date, so this is how payments confirmed later (boleto, Pix) are updated. Orders whose payment is still open are also re-read on every sync, for up to 90 days, until their payment is confirmed, canceled or expires.
  • Refunds Lookback Days: (Optional, default 180) On every sync, the orders created in this many days back (from today) whose payment was refunded, charged back or canceled are read again, even when they are older than the Lookback Days window. This keeps a payment reversed months after the order up to date, so a receivable already marked as received can be reopened. Set it to 0 to turn it off; the maximum is 730.
Once you’re done, click Next.

​
2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.
Tip: The stream can be found more easily by typing its name.
Select the streams and click Next.

​
3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.
  • Layer: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
  • Folder: a folder can be created inside the selected layer to group all tables being created from this new data source.
  • Table name: we suggest a name, but feel free to customize it. You have the option to add a prefix to all tables at once and make this process faster!
  • Sync Type: you can choose between INCREMENTAL and FULL_TABLE.
    • Incremental: every time the extraction happens, we’ll get only the new data, which is good if, for example, you want to keep every record ever fetched.
    • Full table: every time the extraction happens, we’ll get the current state of the data, which is good if, for example, you don’t want to have deleted data in your catalog.
Keep Orders, Order Payments and Order Items as INCREMENTAL. If you set Order Payments or Order Items to FULL_TABLE, every sync reads all orders since the Start Date again. When you select one of these streams later, its first sync reads all orders since the Start Date.
Once you are done configuring, click Next.

​
4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times). Optionally, you can define some additional settings:
  • Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource here.
  • Determine when to execute an Additional Full Sync. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while. A periodic full sync also picks up refunds and chargebacks older than the Refunds Lookback Days. On a full sync (and on the first sync) the connector reads every order before loading anything, so if the sync fails midway your tables keep their previous data instead of being replaced by a partial copy.
Once you are ready, click Next to finalize the setup.

​
5. Check your new source

You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your Catalog, you need at least one successful source run.

​
Streams and Fields

​
Available streams

The table below lists every stream, its slug (the exact identifier to pass when creating the source via API) and a short description.

​
Fields by stream

One row per order, updated incrementally by its creation date (see Lookback Days).Identification and status:
  • id - Internal identifier of the order
  • reference_id - Public order number shown to the buyer
  • status - Order status (CANCELED, COMPLETED, FAILED, PENDING, PROCESSING, REFUNDED)
  • source - Channel of the order (STOREFRONT, CART_TEMPLATE, PAYMENT_LINK)
  • created_at - When the order was created, UTC (incremental key)
  • updated_at - When the order was last updated, UTC
Buyer:
  • email - E-mail entered on the order
  • buyer_name, buyer_tax_payer_id, buyer_is_company - Name and CPF or CNPJ of the buyer, from the billing address of the payment (or the delivery address)
  • account_id, account_name, account_email, account_external_id - Buyer’s account in the store, when the order is linked to one
Amounts:
  • total - Total charged for the order
  • item_total, discount_total, total_savings, fulfillment_total, tax_total, surcharge_total, total_without_discounts - Order totals
  • installment_amount, interest, total_before_interest - Installment details, when the order was paid in installments
  • currency - Currency (for example, BRL)
Payment summary:
  • payments_count - Number of payments of the order
  • payment_status - Current status of the most recent payment
  • payment_method - Method of the most recent payment (unboxpay_credit, unboxpay_boleto, unboxpay_pix)
  • payment_transaction_id - Transaction id of the most recent payment
  • paid_at - First moment a payment of the order was confirmed (PAID or CAPTURED), UTC
  • paid_amount - Sum of the payments currently PAID or CAPTURED
Flags:
  • invoice_issued, sent_to_erp, sent_to_lp, sold_to_company, is_boleto_paid - Invoice, ERP, logistics and boleto flags
  • dispatched, delivered, problem_delivering, shipping_label_pending, shipping_label_failed - Delivery flags
Links to other data:
  • payment_link_id, payment_link_reference_id, payment_link_external_id, payment_link_title - Payment link that originated the order
  • recurring_order_id, recurring_order_cycle_id, recurring_order_frequency_id, generated_new_recurring_order - Subscription that generated the order
  • cart_id - Cart the order came from
  • total_item_quantity - Sum of item quantities
Details as JSON text:
  • payments - Payments as returned by Unbox, with status history and billing address
  • discounts, fulfillment_groups, invoices, shop_sales, surcharges, notes - Other details of the order
One row per payment of an order.
  • order_id, payment_id - Order and payment (together they identify the row); join order_id to orders.id
  • order_reference_id, order_status, order_created_at - Order number, status and creation date (incremental key)
  • transaction_id - Transaction id at Unbox Pay, to match the Unbox Pay statement
  • amount, currency - Gross amount charged to the buyer, including installment interest
  • method_name, method_display_name, method_plugin_name, display_name, processor, mode - Payment method details
  • status, status_at, status_created_by, status_triggered_by - Current status and when it was reached
  • paid_at - First moment the payment was confirmed (PAID or CAPTURED), UTC
  • authorized_at, canceled_at, refunded_at, charged_back_at, expired_at, failed_at - First moment the payment reached each status, UTC
  • status_history - Every status change as JSON text
  • card_brand, is_captured, is_authorization_canceled, capture_error_code, capture_error_message, risk_level, took_loss_on_sale - Card and anti-fraud details
  • billing_full_name, billing_tax_payer_id, billing_is_commercial, billing_phone, billing_city, billing_region, billing_postal - Payer from the billing address
  • order_total, order_installment_amount, order_interest - Order amounts
  • created_at - When the payment was created, UTC
One row per item of an order.
  • order_id, fulfillment_group_id, item_id - Order, delivery group and item (together they identify the row)
  • order_reference_id, order_created_at - Order number and creation date (incremental key)
  • title, variant_title, option_title - Product, variant and option titles
  • product_id, product_variant_id, product_erp_code, variant_erp_code, product_slug, product_type, product_vendor - Product identifiers
  • quantity, price, original_price, subtotal, tax, currency - Quantity and amounts
  • status, cancel_reason - Item status
  • is_recurring, is_discounted_bonus_item, is_taxable, tax_code - Item flags
  • attributes - Item attributes as JSON text
  • added_at, created_at, updated_at - Item dates, UTC
One row per subscription. Read in full on every sync.
  • id, reference_id - Identifiers of the subscription; orders it generates carry id in orders.recurring_order_id
  • customer_account_id, unbox_pay_customer_id - Customer of the subscription
  • status, status_at, status_triggered_by, status_history - Status (ACTIVE, CANCELED, PAUSED, ERROR) and its history
  • frequency_id, frequency_title, frequency_periodicity, frequency_interval - Frequency
  • pricing_policy_type, pricing_policy_value - Price policy of the cycles
  • cycle_count, skip_next_cycle, last_cycle_date, next_cycle_date - Cycles
  • discount_id, discount_code - Discount of the subscription
  • total_amount, currency - Estimate of the next cycle amount (the amount actually charged is on the generated order)
  • items - Items of each new cycle as JSON text
  • created_at, updated_at - Dates, UTC

​
Implementation Notes

​
Data Quality Considerations

  • Amounts are the gross amounts charged to the buyer. Unbox Pay fees, net amounts and release dates are not available through the API.
  • paid_at comes from the payment status history: the first time the payment reached PAID or CAPTURED. It is the date the buyer paid, not the date the money is credited to your bank account.
  • Refunds, chargebacks and cancellations are picked up for orders created in the last Refunds Lookback Days (180 by default). Older ones need a full sync.
  • order_payments.payment_id and order_items.item_id are the ids Unbox gives each payment and item. If Unbox ever omits one, the payment’s transaction id is used, and otherwise the position in the order (<order id>:<position>).
  • If an older order with an open payment can no longer be read from Unbox, it stops being refreshed and the sync log shows a warning.

​
API Limits & Performance

  • Orders are read in pages of 50 (smaller pages when Unbox is slow), in 15-day periods. The first sync of a store with a long history takes longer; later syncs only read the lookback window plus the orders with an open payment.
  • Unbox does not publish its rate limit. The connector makes at most about 4 requests per second and waits when Unbox asks it to slow down.

​
Troubleshooting