Bucket Integration

What is the Bucket integration?

The Bucket integration is the integration method for enterprise operations that already centralize their data in a data warehouse (e.g. BigQuery). Instead of using a native integration or the API, the client periodically exports sales data and journey events (web and app) to a cloud bucket (AWS S3 or Google Cloud Storage), and Nemu reads these files directly from there.

Bucket access

AWS (S3)
GCP (Cloud Storage)

Nemu creates a dedicated IAM role for the client and shares its ARN (e.g. arn:aws:iam::<nemu-account>:role/<client>-s3-bucket-access). The client then:

Grants read access to this role on the bucket (bucket policy);
Confirms the bucket name, folder (prefix) and region (e.g. us-east-1) with Nemu.

Alternatively, the client can create the role on their side and share access with Nemu.

Nemu provides the identity (service account) that needs read permission on the bucket. The client:

Grants Nemu’s service account the object reader role (roles/storage.objectViewer) on the bucket;
Confirms the bucket name, folder (prefix) and region/location with Nemu.

File format

The format used is NDJSON (one JSON object per line): it represents nested structures (such as the products list) without ambiguity and is natively exported by BigQuery.

Sending CSV files is possible, but the file layout must be validated with Nemu before sending starts.

In NDJSON the value type matters: numbers go without quotes (e.g. "campaign_id": 120210948573, "netValue": 699.99) and text goes with quotes (e.g. "content": "CARROSSEL_1080x1080"). In CSV everything is text, and Nemu converts it based on the field type in the mapping. If the type is wrong (e.g. a number sent as text), the mapping flags it before importing.

Folder structure in the bucket

Inside the agreed prefix, organize files by journey and by date. The journey folders are sales/ (sales) and events/ (journey events):

acme-analytics-exports/
└── nemu/
    ├── sales/            ← sales
    │   └── 2026/03/14/   ← year / month / day
    │       └── orders.ndjson
    └── events/           ← journey events
        └── 2026/03/14/
            └── events.ndjson

Nemu runs the imports automatically, during off-peak hours. You don’t need to schedule anything.

Sales schema

Each record represents an order (or one order per seller, in the case of marketplaces, see Multi-seller). products[] is optional, but if sent it must have at least 1 item.

Example

An order with two products:

Order with two products

{
  "transactionId": "155480144",
  "name": "Adidas Dropset 4 Power Trainer Men's Sneakers",
  "netValue": 789.89,
  "grossValue": 789.89,
  "quantity": 1,
  "status": "paid",
  "paymentType": "credit_card",
  "customerName": "John Smith",
  "customerEmail": "customer@email.com",
  "date": "2026-06-28",
  "subscriptionId": "",
  "customerPhone": "+55 11 98888-7777",
  "orderCreatedAt": "2026-06-28 19:39:16",
  "priceCost": 470.00,
  "utm_source": "google",
  "utm_medium": "cpc",
  "utm_campaign": "PMAX_SHOES_JUN",
  "utm_content": "CARROSSEL-IMAGEM_1080x1080",
  "utm_term": "adidas dropset sneakers",
  "isFromApp": false,
  "coupons": ["CUPOM10"],
  "products": [
    {
      "productId": "FBA-83CC-256-42",
      "name": "Adidas Dropset 4 Power Trainer Men's Sneakers",
      "quantity": 1,
      "netValue": 699.99,
      "grossValue": 699.99,
      "priceCost": 420.00,
      "brand": "Adidas",
      "category": { "id": "15", "name": "Shoes" }
    },
    {
      "productId": "MEIA-77AB-40",
      "name": "Nike Sports Socks (Crew)",
      "quantity": 1,
      "netValue": 89.90,
      "grossValue": 89.90,
      "priceCost": 50.00,
      "brand": "Nike",
      "category": { "id": "22", "name": "Accessories" }
    }
  ]
}

Order fields

Field	Type	Required	Description
`transactionId`	string	✅	Unique order identifier (deduplication key)
`parentOrderId`	string	➖	Parent order id, groups child orders from different sellers (marketplace, see Multi-seller)
`name`	string	✅	Order name / main product
`netValue`	number	✅	Net revenue of the order
`grossValue`	number	✅	Gross revenue of the order
`quantity`	number	✅	Total number of items
`status`	string	✅	Order status: `paid`, `waiting_payment`, `cancelled`, `chargeback`, `refunded` or `checkout_completed`
`paymentType`	string	✅	Payment method: `billet`, `credit_card`, `pix` or `others`
`customerName`	string	✅	Customer name
`customerEmail`	string	✅	Customer email. Accepts plain text or a hashed email value (e.g. SHA-256)
`date`	string	✅	Order date in `YYYY-MM-DD` format
`subscriptionId`	string	➖	Subscription identifier, when applicable
`customerPhone`	string	➖	Customer phone
`orderCreatedAt`	string	➖	Order creation time in `YYYY-MM-DD HH:mm:ss` format
`priceCost`	number	➖	Product cost (used to calculate margin)
`utm_source`	string	➖	UTM source of the sale
`utm_medium`	string	➖	UTM medium of the sale
`utm_campaign`	string	➖	UTM campaign of the sale
`utm_content`	string	➖	UTM content of the sale
`utm_term`	string	➖	UTM term of the sale, which carries Nemu’s packed attribution data (see Configuring UTMs)
`isFromApp`	boolean	➖	`true` when the sale happened in the app
`coupons`	array	➖	List of discount coupon codes applied to the order (e.g. `["CUPOM10"]`)
`products`	array	➖	List of products in the order (at least 1 item when sent), see below

Product fields (`products[]`)

Field	Type	Required	Description
`productId`	string	✅	Unique product identifier (SKU)
`name`	string	✅	Product name
`netValue`	number	✅	Net unit value
`grossValue`	number	✅	Gross unit value
`quantity`	integer	✅	Quantity (minimum `1`)
`priceCost`	number	➖	Product cost
`brand`	string	➖	Product brand (e.g. `Adidas`)
`category`	object	➖	Product category
`category.name`	string	✅*	Category name (*required if `category` is sent)
`category.id`	string	➖	Category identifier
`category.imageUrl`	string	➖	Category image URL

Multi-seller (marketplaces)

For marketplace operations, each child order (per seller) is sent as its own record, linked to the “parent” order by the fields:

Field	Type	Description
`transactionId`	string	Child order id, used as the dedup key (e.g. `155480144-1`)
`parentOrderId`	string	Parent order id that groups the sellers

The parent order doesn’t need to be sent or have its own status: the status comes in each child, and Nemu groups by parentOrderId, adding or subtracting each child according to its status (delivered counts, cancelled or returned is removed). These fields are optional: if you’re not a marketplace, simply don’t send parentOrderId. In the example below, order 155480144 has items from two sellers and is sent as two child orders:

Child order 1

{
  "transactionId": "155480144-1",
  "parentOrderId": "155480144",
  "name": "Adidas Dropset 4 Sneakers",
  "netValue": 699.99,
  "grossValue": 699.99,
  "quantity": 1,
  "status": "paid",
  "paymentType": "credit_card",
  "customerName": "John Smith",
  "customerEmail": "customer@email.com",
  "date": "2026-06-28",
  "orderCreatedAt": "2026-06-28 19:39:16",
  "isFromApp": false,
  "products": [
    {
      "productId": "FBA-83CC-256-42",
      "name": "Adidas Dropset 4 Sneakers",
      "quantity": 1,
      "netValue": 699.99,
      "grossValue": 699.99,
      "priceCost": 420.0,
      "category": { "id": "15", "name": "Shoes" }
    }
  ]
}

Child order 2

{
  "transactionId": "155480144-2",
  "parentOrderId": "155480144",
  "name": "Nike Sports Socks (Crew)",
  "netValue": 49.9,
  "grossValue": 49.9,
  "quantity": 2,
  "status": "cancelled",
  "paymentType": "credit_card",
  "customerName": "John Smith",
  "customerEmail": "customer@email.com",
  "date": "2026-06-28",
  "orderCreatedAt": "2026-06-28 19:39:16",
  "isFromApp": false,
  "products": [
    {
      "productId": "MEIA-77AB-40",
      "name": "Nike Sports Socks",
      "quantity": 2,
      "netValue": 24.95,
      "grossValue": 24.95,
      "category": { "id": "22", "name": "Accessories" }
    }
  ]
}

In the NDJSON file, each of these records takes up a single line. The formatting above is just for readability.

Sub-orders of the same parent order can have different statuses (e.g. one seller paid and another cancelled). Send the actual status of each sub-order.

Journey events schema

Journey events (web and app) follow the GA4/BigQuery export standard. Each record represents one event. user_pseudo_id is almost always present; user_id only when the user has logged in. transaction_id ties the purchase event to the sale.

Example

A purchase event with full attribution:

purchase event

{
  "event_date": "2026-07-11",
  "event_timestamp": "2026-07-11 16:53:56",
  "user_pseudo_id": "00de56a47fde1207286aa3325eb6714d",
  "user_id": "2c17315c-8e85-4b71-825a-02c63a0db79d",
  "session_id": "1783788836",
  "platform": "WEB",
  "event_name": "purchase",
  "transaction_id": "155480144",
  "source": "google",
  "medium": "cpc",
  "campaign_name": "RTG_VSA_SMART_VALOR_PANGLE",
  "campaign_id": 120210948573,
  "term": "nike sneakers",
  "content": "CARROSSEL-IMAGEM_1080x1080",
  "gclid": "Cj0KCQjw_8mHBhClARIsAP",
  "channel_group": "Paid Search",
  "item_id": "D74-58FP-008"
}

Event fields

Field	Type	Required	Description
`event_date`	string	✅	Event date in `YYYY-MM-DD` format (e.g. `2026-07-11`)
`event_timestamp`	string	✅	Exact time of the event, in `YYYY-MM-DD HH:mm:ss` format, used to order the journey
`user_pseudo_id`	string	✅	Anonymous device/browser id (e.g. `00de56a47fde1207286aa3325eb6714d`)
`user_id`	string	➖	Logged-in user id (only when a login happened)
`session_id`	string	➖	Session/visit id, which ties together events from the same browsing session (e.g. `1783788836`)
`platform`	enum	✅	Where the event happened: `WEB`, `ANDROID` or `IOS`
`event_name`	enum	✅	Event action (enables the funnel): `page_view`, `view_item`, `add_to_cart`, `begin_checkout`, `add_shipping_info`, `add_payment_info` or `purchase`
`transaction_id`	string	➖	Order id in the `purchase` event, the bridge between journey and sale (e.g. `155480144`)
`source`	string	➖	Traffic source (e.g. `google`, `tiktok`, `facebook`)
`medium`	string	➖	Traffic medium/channel (e.g. `cpc`, `organic`, `email`, `catalogo`)
`campaign_name`	string	➖	Marketing campaign name (e.g. `RTG_VSA_SMART_VALOR_PANGLE`)
`campaign_id`	number	➖	Numeric campaign id, more reliable than the name (e.g. `120210948573`)
`term`	string	➖	Search keyword/term or segment (e.g. `nike sneakers`)
`content`	string	➖	Variation/creative of the clicked ad (e.g. `CARROSSEL-IMAGEM_1080x1080`)
`gclid`	string	➖	Google Click Id, which matches the click with the Google Ads cost
`channel_group`	enum	➖	Channel grouping calculated by GA4: `Paid Social`, `Paid Search`, `Organic`, `Direct` or `Unassigned`
`item_id`	string	➖	Product id of the event, a possible bridge with the sale’s `productId` (e.g. `D74-58FP-008`)

The transaction_id of the purchase event must be the same transactionId sent in the sales file. It’s what connects the browsing journey to the sale inside Nemu.

Configuring UTMs

In this integration, UTM configuration does not follow Nemu’s standard onboarding. Since the utm_source, utm_medium, utm_campaign and utm_content fields are usually already in use by the client’s GA4 and can’t be changed, all of Nemu’s attribution (source, campaign, ad set and creative) is packed into a single utm_term, which GA4 captures and passes on to Nemu. See the step-by-step guide per platform (Meta, Google and TikTok) in Configuring UTMs.

Validation checklist

After the files start being sent, the client and Nemu validate the data loaded on the platform together:

Payment methods: all of the client’s methods are correctly mapped to billet, credit_card, pix or others;
Revenue: net (netValue) and gross (grossValue) revenue values match the client’s platform;
Products: name, quantity and values of each product are correct;
Orders: transactionId and revenue of each order match;
UTMs: utm_term is arriving in Nemu’s packed attribution format (see Configuring UTMs).

The integration is only considered complete after every checklist item has been validated by both sides. Revenue discrepancies or payment mapping issues must be fixed at the source (the client’s export) before go-live.

​What is the Bucket integration?

​Bucket access

​File format

​Folder structure in the bucket

​Sales schema

​Example

​Order fields

​Product fields (products[])

​Multi-seller (marketplaces)

​Journey events schema

​Example

​Event fields

​Configuring UTMs

​Validation checklist

What is the Bucket integration?

Bucket access

File format

Folder structure in the bucket

Sales schema

Example

Order fields

Product fields (`products[]`)

Multi-seller (marketplaces)

Journey events schema

Example

Event fields

Configuring UTMs

Validation checklist