Selling

Orders, Payments & Fees

Capture the outcome of a sale as an order, apply configured fees, issue invoices, and record payment.

After an item is won (or sold directly), Basta can capture the outcome as an order, apply your configured fees, issue an invoice, and record payment. This page gives a high-level overview of those concepts and the operations available through the Management API.

All monetary amounts are in minor currency units (e.g. cents for USD). For example, 1000 = $10.00.

The order lifecycle

Text

DRAFT ──▶ OPEN ──▶ INVOICE_ISSUED ──▶ PAID
                └──▶ CANCELLED

Status	Meaning
`DRAFT`	Order is being assembled
`OPEN`	Order has been placed / published
`INVOICE_ISSUED`	An invoice has been issued to the buyer
`PAID`	The order has been paid
`CANCELLED`	The order was cancelled

An order belongs to a buyer and references the sale and item it came from. It is made up of one or more order lines — each line has an amount, a description, and any associated fees.

Common operations

Operation	Purpose
`createOrder`	Create an order
`updateOrder`	Update an order
`cancelPaymentOrder`	Cancel an order
`publishPaymentOrder`	Publish an order
`createOrderLine` / `updateOrderLine` / `deleteOrderLine`	Manage line items
`createInvoice`	Issue an invoice for an order
`createPayment`	Record a payment against an order
`orders` / `userOrders`	List orders for an account or a user

Example: fetch orders

GraphQL

query Orders {
  orders(accountId: "ACCOUNT_ID", first: 20) {
    edges {
      node {
        id
        title
        currency
        status
        orderLines {
          orderLineId
          amount
          description
          fees { name amount }
        }
        invoice { invoiceId dueDate url }
      }
    }
  }
}

Fees

Fees let you add charges such as a buyer's premium on top of the hammer price, or seller-side charges. Fees are defined as rules and applied automatically when orders are created.

Fee rule anatomy

Field	Description
`name`	Label shown on the order/invoice
`type`	`PERCENTAGE` or `AMOUNT`
`value`	`500` = 5% (percentage) or `1000` = $10 (amount)
`lowerLimit` / `upperLteLimit`	The amount bracket this rule applies to
`calculationType`	`FLAT` (rate applied to the whole amount) or `PROGRESSIVE` (rate applied only to the portion within each bracket)

Cascading levels

Fee rules cascade across three levels — the most specific level wins:

Text

Account defaults  ──▶  Sale overrides  ──▶  Item overrides

Level	Set with	Applies to
Account	`createAccountFee`	Default for every sale on the account
Sale	`createSaleFee`	A specific sale (overrides account)
Item	`createSaleItemFee`	A specific item (overrides sale)

When you query effective fees, each rule reports its source (ACCOUNT, SALE, or ITEM) so you can see where it came from. Use resetSaleFees to discard sale-level customizations and fall back to account defaults.

Example: account-level buyer's premium

GraphQL

mutation CreateBuyersPremium {
  createAccountFee(accountId: "ACCOUNT_ID", input: {
    name: "Buyer's Premium"
    type: PERCENTAGE
    value: 2000        # 20%
    lowerLimit: 0
  }) {
    id
    name
    type
    value
  }
}

Payments

Basta integrates with a payment provider to collect funds and manage buyer payment methods. Where a provider session is needed (for example, to render a secure payment UI), the API issues short-lived provider session credentials rather than exposing sensitive details to the browser. Buyers can also be surfaced their saved payment methods and a default selection.

The specifics of payment collection depend on your account's configuration — contact us to enable and configure payments for your account.

Staying in sync

Order changes emit webhook events:

OrderCreated
OrderUpdated
OrderCancelled

See Webhooks for payloads and Managing Webhooks to subscribe.