Shop API

Sales channels, stock, shipping and orders — from basket to doorstep.

Module code retail · 74 actions · 33 data models · 56 events. A key or token never does more here than the person behind it can; row-level security applies exactly as in the app. Scopes: retail (everything), retail:read (read only) or retail:<capability>.

Resources

Lists take limit (up to 200), cursor, order (e.g. -created_at), fields and q; every other query parameter is a column filter: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

Actions

retail.adjust_stock

Adjust stock — Goods in or out of one warehouse by an amount, with a reason for the ledger.

Needs retail:write · changes data

• Canonical address: POST /api/v1/actions/retail.adjust_stock

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.stock_changed, retail.stock_low

What it writes: stock (upsert) — Moves the count by the amount, in the statement; stock_movement (insert) — Records the movement and its reason

curl -X POST https://app.getera.io/api/v1/stocks/actions/adjust_stock \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"warehouseId":"WAREHOUSE_ID","itemVariantId":"ITEM_VARIANT_ID","delta":1,"reason":"count"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.stock_changed",
    "retail.stock_low"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.stocks.adjustStock({
  warehouseId: "WAREHOUSE_ID",
  itemVariantId: "ITEM_VARIANT_ID",
  delta: 1,
  reason: "count"
})

era stocks adjust_stock \
  --warehouse-id "WAREHOUSE_ID" \
  --item-variant-id "ITEM_VARIANT_ID" \
  --delta 1 \
  --reason "count"

{
  "name": "era__retail__adjust_stock",
  "arguments": {
    "warehouseId": "WAREHOUSE_ID",
    "itemVariantId": "ITEM_VARIANT_ID",
    "delta": 1,
    "reason": "count"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 no_change, warehouse_not_found, variant_not_found, below_allocated · 429 slow down

retail.approve_fulfilment

Approve a despatch — Only needed when the shop does not approve despatches automatically.

Needs retail:approve · changes data

• Canonical address: POST /api/v1/actions/retail.approve_fulfilment

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.fulfilment_approved

What it writes: fulfilment (update) — Marks it fulfilled

curl -X POST https://app.getera.io/api/v1/fulfilments/FULFILMENT_ID/actions/approve_fulfilment \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.fulfilment_approved"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.fulfilments.approveFulfilment("FULFILMENT_ID")

era fulfilments approve_fulfilment FULFILMENT_ID

{
  "name": "era__retail__approve_fulfilment",
  "arguments": {
    "id": "FULFILMENT_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:approve · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, fulfilment_not_awaiting · 429 slow down

retail.attach_gift_card

Pay with a gift card — One call: records the spend as pending and asks gift_cards to redeem it (a reaction); a refusal marks it failed and puts the amount back.

Needs retail:write · removes or cannot be undone

• Canonical address: POST /api/v1/actions/retail.attach_gift_card

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.gift_card_requested, retail.gift_card_applied

What it writes: sales_order_gift_card (insert) — Records the spend (pending until redeemed); sales_order_gift_card (delete) — A failed try of the same card gives way to the new one; sales_order (update) — Lowers the amount due

curl -X POST https://app.getera.io/api/v1/orders/ORDER_ID/actions/attach_gift_card \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"amount":1}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.gift_card_requested",
    "retail.gift_card_applied"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.orders.attachGiftCard("ORDER_ID", {
  amount: 1
})

era orders attach_gift_card ORDER_ID \
  --amount 1

{
  "name": "era__retail__attach_gift_card",
  "arguments": {
    "id": "ORDER_ID",
    "amount": 1
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, order_not_editable, gift_card_not_on_order, gift_card_exceeds_due · 429 slow down

retail.bulk_update_prices

Reprice in bulk — One rule — set, or up or down by an amount or a percent — over many variants in a channel.

Needs retail:write · changes data

• Canonical address: POST /api/v1/actions/retail.bulk_update_prices

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.channel_price_changed

What it writes: item_variant_channel_listing (upsert) — Writes each new channel price or cost

curl -X POST https://app.getera.io/api/v1/variant_listings/actions/bulk_update_prices \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"channelId":"CHANNEL_ID","itemVariantIds":{},"mode":"set","value":1}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.channel_price_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.variantListings.bulkUpdatePrices({
  channelId: "CHANNEL_ID",
  itemVariantIds: {},
  mode: "set",
  value: 1
})

era variant_listings bulk_update_prices --data '{"channelId":"CHANNEL_ID","itemVariantIds":{},"mode":"set","value":1}'

{
  "name": "era__retail__bulk_update_prices",
  "arguments": {
    "channelId": "CHANNEL_ID",
    "itemVariantIds": {},
    "mode": "set",
    "value": 1
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 channel_not_found, no_variants, variant_not_found, negative_price · 429 slow down

retail.cancel_fulfilment

Cancel a despatch — The goods go back to the shelf they left from.

Needs retail:handle · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/retail.cancel_fulfilment

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.fulfilment_canceled

What it writes: fulfilment (update) — Marks it cancelled; stock (update) — Puts the goods back; sales_order_line (update) — Lowers quantity_fulfilled

curl -X POST https://app.getera.io/api/v1/fulfilments/FULFILMENT_ID/actions/cancel_fulfilment \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.fulfilment_canceled"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.fulfilments.cancelFulfilment("FULFILMENT_ID")

era fulfilments cancel_fulfilment FULFILMENT_ID

{
  "name": "era__retail__cancel_fulfilment",
  "arguments": {
    "id": "FULFILMENT_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, fulfilment_not_cancellable · 429 slow down

retail.cancel_order

Cancel an order — Releases everything it was holding. The goods never left the shelf.

Needs retail:manage · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/retail.cancel_order

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.order_canceled, retail.gift_card_removed, retail.customer_notification_requested

What it writes: sales_order (update) — Marks it cancelled; allocation (delete) — Releases the stock it held; stock (update) — Lowers the allocated count; sales_order_gift_card (delete) — Gives every gift card back (gift_cards refunds it, a reaction)

curl -X POST https://app.getera.io/api/v1/orders/ORDER_ID/actions/cancel_order \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"reason":"Reason"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.order_canceled",
    "retail.gift_card_removed",
    "retail.customer_notification_requested"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.orders.cancelOrder("ORDER_ID", {
  reason: "Reason"
})

era orders cancel_order ORDER_ID \
  --reason "Reason"

{
  "name": "era__retail__cancel_order",
  "arguments": {
    "id": "ORDER_ID",
    "reason": "Reason"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, order_not_cancellable, order_has_fulfilments, gift_card_pending · 429 slow down

retail.close_return

Close a return — Nothing more will happen on it.

Needs retail:handle · changes data

• Canonical address: POST /api/v1/actions/retail.close_return

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.return_closed

What it writes: order_return (update) — Marks it closed

curl -X POST https://app.getera.io/api/v1/order_returns/ORDER_RETURN_ID/actions/close_return \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.return_closed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.orderReturns.closeReturn("ORDER_RETURN_ID")

era order_returns close_return ORDER_RETURN_ID

{
  "name": "era__retail__close_return",
  "arguments": {
    "id": "ORDER_RETURN_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 return_not_found, return_not_open · 429 slow down

retail.complete_checkout

Place the order — Turns a basket into an order, allocates stock and closes the basket — once.

Needs retail:write · removes or cannot be undone

• Canonical address: POST /api/v1/actions/retail.complete_checkout

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.order_placed, retail.customer_notification_requested, retail.stock_low, retail.order_discounts_applied

What it writes: sales_order (insert) — Writes the order; sales_order_line (insert) — Writes its lines, frozen; allocation (insert) — Promises stock to the order; stock (update) — Raises the allocated count; stock_reservation (update) — Commits the basket hold into the order allocation; checkout (delete) — Closes the basket

curl -X POST https://app.getera.io/api/v1/orders/actions/complete_checkout \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"token":"TOKEN_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.order_placed",
    "retail.customer_notification_requested",
    "retail.stock_low",
    "retail.order_discounts_applied"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.orders.completeCheckout({
  token: "TOKEN_ID"
})

era orders complete_checkout \
  --token "TOKEN_ID"

{
  "name": "era__retail__complete_checkout",
  "arguments": {
    "token": "TOKEN_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, checkout_completing, checkout_empty, prices_stale, order_not_paid, shipping_address_missing, insufficient_stock, voucher_not_applicable, voucher_usage_exceeded · 429 slow down

retail.complete_draft_order

Place a draft order — Allocates stock and moves the draft into the order lifecycle.

Needs retail:write · changes data

• Canonical address: POST /api/v1/actions/retail.complete_draft_order

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.order_placed, retail.order_discounts_applied, retail.customer_notification_requested, retail.stock_low

What it writes: sales_order (update) — Moves it out of draft; sales_order_line (update) — Freezes the discount snapshot; sales_order_discount (insert) — Records what was applied; allocation (insert) — Promises stock to the order; preorder_allocation (insert) — Promises preorders; stock (update) — Raises the allocated count

curl -X POST https://app.getera.io/api/v1/orders/ORDER_ID/actions/complete_draft_order \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.order_placed",
    "retail.order_discounts_applied",
    "retail.customer_notification_requested",
    "retail.stock_low"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.orders.completeDraftOrder("ORDER_ID")

era orders complete_draft_order ORDER_ID

{
  "name": "era__retail__complete_draft_order",
  "arguments": {
    "id": "ORDER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, not_a_draft, order_empty, gift_card_pending, shipping_address_missing, insufficient_stock, voucher_not_found, voucher_not_applicable, voucher_usage_exceeded · 429 slow down

retail.confirm_gift_card

Confirm a gift card redemption — Machine-only (finance-reactions.ts): gift_cards redeemed the card, so the pending row on the order is applied.

Needs retail:write · changes data

• Canonical address: POST /api/v1/actions/retail.confirm_gift_card

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.gift_card_applied

What it writes: sales_order_gift_card (update) — Applies the pending row

Errors: 401 no or expired credential · 403 the credential does not hold retail:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 gift_card_not_on_order · 429 slow down

retail.confirm_order

Confirm an order — The step that exists only when the channel does not confirm automatically.

Needs retail:approve · changes data

• Canonical address: POST /api/v1/actions/retail.confirm_order

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.order_confirmed

What it writes: sales_order (update) — Moves it to unfulfilled

curl -X POST https://app.getera.io/api/v1/orders/ORDER_ID/actions/confirm_order \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.order_confirmed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.orders.confirmOrder("ORDER_ID")

era orders confirm_order ORDER_ID

{
  "name": "era__retail__confirm_order",
  "arguments": {
    "id": "ORDER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:approve · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, order_not_unconfirmed · 429 slow down

retail.create_checkout

Open a basket — A basket in one channel, for a customer or a guest.

Needs retail:write · changes data

• REST alias: POST /api/v1/checkouts
• Canonical address: POST /api/v1/actions/retail.create_checkout

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.checkout_created

What it writes: checkout (insert) — Opens the basket; checkout_line (upsert) — Writes its lines; stock_reservation (upsert) — Holds tracked stock for fifteen minutes

curl -X POST https://app.getera.io/api/v1/checkouts/actions/create_checkout \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"channelId":"CHANNEL_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.checkout_created"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.checkouts.create({
  channelId: "CHANNEL_ID"
})

era checkouts create \
  --channel-id "CHANNEL_ID"

{
  "name": "era__retail__create_checkout",
  "arguments": {
    "channelId": "CHANNEL_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 channel_not_found, channel_closed, malformed_lines, variant_not_found, variant_not_priced, reservation_stock_unavailable, gift_line_locked · 429 slow down

retail.create_draft_order

Start a draft order — The shop assistant’s version of a basket: an order nobody has placed yet.

Needs retail:write · changes data

• REST alias: POST /api/v1/orders
• Canonical address: POST /api/v1/actions/retail.create_draft_order

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.draft_order_created

What it writes: sales_order (insert) — Writes the draft

curl -X POST https://app.getera.io/api/v1/orders/actions/create_draft_order \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"channelId":"CHANNEL_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.draft_order_created"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.orders.create({
  channelId: "CHANNEL_ID"
})

era orders create \
  --channel-id "CHANNEL_ID"

{
  "name": "era__retail__create_draft_order",
  "arguments": {
    "channelId": "CHANNEL_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 channel_not_found, channel_closed · 429 slow down

retail.create_warehouse

Open a warehouse — A place stock is held and orders are despatched from.

Needs retail:manage · changes data

• REST alias: POST /api/v1/warehouses
• Canonical address: POST /api/v1/actions/retail.create_warehouse

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.warehouse_saved

What it writes: warehouse (insert) — Creates the warehouse

curl -X POST https://app.getera.io/api/v1/warehouses/actions/create_warehouse \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Name"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.warehouse_saved"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.warehouses.create({
  name: "Name"
})

era warehouses create \
  --name "Name"

{
  "name": "era__retail__create_warehouse",
  "arguments": {
    "name": "Name"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 invalid_name, slug_taken, address_not_found · 429 slow down

retail.delete_channel

Delete a channel — Only a channel that never took an order or a basket; one that has sold is closed instead.

Needs retail:delete · removes or cannot be undone · asks a person to confirm when Era runs it

• REST alias: DELETE /api/v1/sales_channels/{id}
• Canonical address: POST /api/v1/actions/retail.delete_channel

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.channel_deleted

What it writes: channel (delete) — Removes the channel and its listings

curl -X POST https://app.getera.io/api/v1/sales_channels/SALES_CHANNEL_ID/actions/delete_channel \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.channel_deleted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.salesChannels.deleteChannel("SALES_CHANNEL_ID")

era sales_channels delete_channel SALES_CHANNEL_ID

{
  "name": "era__retail__delete_channel",
  "arguments": {
    "id": "SALES_CHANNEL_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 channel_not_found, channel_in_use · 429 slow down

retail.delete_collection

Delete a collection — The list goes; the items in it are the catalogue’s and stay.

Needs retail:delete · removes or cannot be undone · asks a person to confirm when Era runs it

• REST alias: DELETE /api/v1/collections/{id}
• Canonical address: POST /api/v1/actions/retail.delete_collection

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.collection_deleted

What it writes: item_collection (delete) — Removes the collection

curl -X POST https://app.getera.io/api/v1/collections/COLLECTION_ID/actions/delete_collection \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.collection_deleted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.collections.deleteCollection("COLLECTION_ID")

era collections delete_collection COLLECTION_ID

{
  "name": "era__retail__delete_collection",
  "arguments": {
    "id": "COLLECTION_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found · 429 slow down

retail.delete_draft_order

Discard a draft order — Removes an order shell only before it is placed.

Needs retail:delete · removes or cannot be undone

• REST alias: DELETE /api/v1/orders/{id}
• Canonical address: POST /api/v1/actions/retail.delete_draft_order

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.draft_order_deleted

What it writes: sales_order (delete) — Removes the draft and its lines

curl -X POST https://app.getera.io/api/v1/orders/ORDER_ID/actions/delete_draft_order \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.draft_order_deleted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.orders.deleteDraftOrder("ORDER_ID")

era orders delete_draft_order ORDER_ID

{
  "name": "era__retail__delete_draft_order",
  "arguments": {
    "id": "ORDER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, not_a_draft, draft_has_gift_cards · 429 slow down

retail.delete_draft_orders

Discard drafts — Several drafts at once, from the orders list. All or none.

Needs retail:delete · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/retail.delete_draft_orders

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.draft_order_deleted

What it writes: sales_order (delete) — Removes the drafts

curl -X POST https://app.getera.io/api/v1/orders/actions/delete_draft_orders \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"ids":{}}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.draft_order_deleted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.orders.deleteDraftOrders({
  ids: {}
})

era orders delete_draft_orders --data '{"ids":{}}'

{
  "name": "era__retail__delete_draft_orders",
  "arguments": {
    "ids": {}
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 no_orders, not_a_draft, draft_has_gift_cards · 429 slow down

retail.delete_shipping_method

Delete a delivery rate — Past orders keep the name they were sold with.

Needs retail:delete · removes or cannot be undone · asks a person to confirm when Era runs it

• REST alias: DELETE /api/v1/shipping_methods/{id}
• Canonical address: POST /api/v1/actions/retail.delete_shipping_method

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.shipping_method_deleted

What it writes: shipping_method (delete) — Removes the rate

curl -X POST https://app.getera.io/api/v1/shipping_methods/SHIPPING_METHOD_ID/actions/delete_shipping_method \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.shipping_method_deleted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.shippingMethods.deleteShippingMethod("SHIPPING_METHOD_ID")

era shipping_methods delete_shipping_method SHIPPING_METHOD_ID

{
  "name": "era__retail__delete_shipping_method",
  "arguments": {
    "id": "SHIPPING_METHOD_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found · 429 slow down

retail.delete_shipping_zone

Delete a shipping zone — Only an empty zone can go; its rates would leave orders without one.

Needs retail:delete · removes or cannot be undone · asks a person to confirm when Era runs it

• REST alias: DELETE /api/v1/shipping_zones/{id}
• Canonical address: POST /api/v1/actions/retail.delete_shipping_zone

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.shipping_zone_deleted

What it writes: shipping_zone (delete) — Removes the zone

curl -X POST https://app.getera.io/api/v1/shipping_zones/SHIPPING_ZONE_ID/actions/delete_shipping_zone \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.shipping_zone_deleted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.shippingZones.deleteShippingZone("SHIPPING_ZONE_ID")

era shipping_zones delete_shipping_zone SHIPPING_ZONE_ID

{
  "name": "era__retail__delete_shipping_zone",
  "arguments": {
    "id": "SHIPPING_ZONE_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, zone_has_methods · 429 slow down

retail.delete_warehouse

Close a warehouse — The warehouse and its address go together, as they do in the source.

Needs retail:delete · removes or cannot be undone · asks a person to confirm when Era runs it

• REST alias: DELETE /api/v1/warehouses/{id}
• Canonical address: POST /api/v1/actions/retail.delete_warehouse

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.warehouse_deleted

What it writes: warehouse (delete) — Removes the warehouse and its stock rows

curl -X POST https://app.getera.io/api/v1/warehouses/WAREHOUSE_ID/actions/delete_warehouse \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.warehouse_deleted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.warehouses.deleteWarehouse("WAREHOUSE_ID")

era warehouses delete_warehouse WAREHOUSE_ID

{
  "name": "era__retail__delete_warehouse",
  "arguments": {
    "id": "WAREHOUSE_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, warehouse_has_allocations · 429 slow down

retail.detach_gift_card

Take a gift card off — Removes a gift card from an order; gift_cards puts the money back onto the card (a reaction). With failure set, it is the compensation of a refused redemption.

Needs retail:write · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/retail.detach_gift_card

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.gift_card_removed

What it writes: sales_order_gift_card (delete) — Removes the spend; sales_order_gift_card (update) — Marks a refused redemption failed; sales_order (update) — Raises the amount due again

curl -X POST https://app.getera.io/api/v1/order_gift_cards/ORDER_GIFT_CARD_ID/actions/detach_gift_card \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"failure":"Why the card was refused (compensation)"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.gift_card_removed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.orderGiftCards.detachGiftCard("ORDER_GIFT_CARD_ID", {
  failure: "Why the card was refused (compensation)"
})

era order_gift_cards detach_gift_card ORDER_GIFT_CARD_ID \
  --failure "Why the card was refused (compensation)"

{
  "name": "era__retail__detach_gift_card",
  "arguments": {
    "id": "ORDER_GIFT_CARD_ID",
    "failure": "Why the card was refused (compensation)"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 gift_card_not_on_order, gift_card_pending, order_not_editable · 429 slow down

retail.duplicate_order

Order again — A new draft with the same customer, addresses and lines, at today’s channel prices.

Needs retail:write · changes data

• Canonical address: POST /api/v1/actions/retail.duplicate_order

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.draft_order_created, retail.order_lines_changed, retail.order_discounts_applied

What it writes: sales_order (insert) — Writes the new draft; sales_order_line (insert) — Copies the lines at today’s prices; sales_order_discount (insert) — Records what applies to the new draft

curl -X POST https://app.getera.io/api/v1/orders/ORDER_ID/actions/duplicate_order \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.draft_order_created",
    "retail.order_lines_changed",
    "retail.order_discounts_applied"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.orders.duplicateOrder("ORDER_ID")

era orders duplicate_order ORDER_ID

{
  "name": "era__retail__duplicate_order",
  "arguments": {
    "id": "ORDER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, channel_closed · 429 slow down

retail.end_preorder

End a preorder — The goods arrived: every preorder becomes a real allocation on a shelf — all of them, or none.

Needs retail:manage · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/retail.end_preorder

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.preorder_ended, retail.stock_low

What it writes: preorder_allocation (delete) — Releases the preorders; variant_preorder (delete) — Ends the preorder; allocation (insert) — Promises the shelf instead; stock (update) — Raises the allocated count

curl -X POST https://app.getera.io/api/v1/allocations/actions/end_preorder \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"itemVariantId":"ITEM_VARIANT_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.preorder_ended",
    "retail.stock_low"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.allocations.endPreorder({
  itemVariantId: "ITEM_VARIANT_ID"
})

era allocations end_preorder \
  --item-variant-id "ITEM_VARIANT_ID"

{
  "name": "era__retail__end_preorder",
  "arguments": {
    "itemVariantId": "ITEM_VARIANT_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 variant_not_found, not_preorder, insufficient_stock · 429 slow down

retail.expire_order

Expire an unconfirmed order — Machine: the shop sweep lets an order nobody confirmed in time go, with its stock and its coupon.

Needs retail:handle · removes or cannot be undone

• Canonical address: POST /api/v1/actions/retail.expire_order

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.order_expired

What it writes: sales_order (update) — Marks it expired; allocation (delete) — Releases the stock it held; stock (update) — Lowers the allocated count

curl -X POST https://app.getera.io/api/v1/orders/ORDER_ID/actions/expire_order \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.order_expired"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.orders.expireOrder("ORDER_ID")

era orders expire_order ORDER_ID

{
  "name": "era__retail__expire_order",
  "arguments": {
    "id": "ORDER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, order_not_expirable · 429 slow down

retail.expire_stock_reservations

Release expired checkout stock — Machine action: releases checkout claims older than fifteen minutes.

Needs retail:handle · changes data

• Canonical address: POST /api/v1/actions/retail.expire_stock_reservations

Input

This action takes no input.

Events it publishes: retail.stock_reservations_expired

What it writes: stock_reservation (update) — Marks expired claims released

curl -X POST https://app.getera.io/api/v1/stock_reservations/actions/expire_stock_reservations \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.stock_reservations_expired"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.stockReservations.expireStockReservations()

era stock_reservations expire_stock_reservations

{
  "name": "era__retail__expire_stock_reservations",
  "arguments": {}
}

Errors: 401 no or expired credential · 403 the credential does not hold retail:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 429 slow down

retail.fulfil_order

Despatch an order — Goods leave a named shelf. This is where the count actually drops.

Needs retail:handle · changes data

• Canonical address: POST /api/v1/actions/retail.fulfil_order

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: retail.fulfilment_created, retail.customer_notification_requested, retail.stock_low

What it writes: fulfilment (insert) — Records the despatch; fulfilment_line (insert) — Records which shelf each line left from; stock (update) — Lowers the count and the allocation; sales_order_line (update) — Raises quantity_fulfilled; sales_order (update) — Settles the order status

curl -X POST https://app.getera.io/api/v1/orders/ORDER_ID/actions/fulfil_order \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"lines":{}}'

{
  "ok": true,
  "result": "…",
  "events": [
    "retail.fulfilment_created",
    "retail.customer_notification_requested",
    "retail.stock_low"
  ]
}