> ## Documentation Index > Fetch the complete documentation index at: https://docs.upstackdata.com/llms.txt > Use this file to discover all available pages before exploring further. # Add a cost line > Add a new cost line for one of the five line-typed cost surfaces — `order`, `gateway`, `shipping` (profile rule), `variable`, or `fixed`. The server assigns a ULID for the new line. The `line` body is discriminated by `costType` — see the per-type schemas (`OrderCostLine`, `GatewayCostLine`, `ShippingProfileCostLine`, `VariableCostLine`, `FixedCostLine`) for the shape required by each. Triggers a per-order COGS recalculation downstream — except for `variable` and `fixed`, which apply at aggregate report time and do not require per-order recalc. **Required scope:** `costs:write`. ## OpenAPI ````yaml /api-reference/openapi.yaml post /accounts/api/costs/lines openapi: 3.1.0 info: title: Upstack Data API version: '1.0' description: > Programmatic access to your Upstack Data pixel — analytics queries, the measures/dimensions catalog, and dashboard view management. All requests authenticate with two headers: - `x-api-key`: your Upstack API key (mint one at **Settings → API Keys** in the dashboard). - `x-pixel-id`: the pixel id the request targets. One key is scoped to one pixel. servers: - url: https://api.upstackdata.com description: Production security: - apiKey: [] pixelId: [] tags: - name: Analytics description: Query events, attribution, and cohort analyses. - name: Catalog description: List the measures available to your pixel. - name: Dashboards description: >- Manage dashboard views — create, update, copy, delete, and the high-level preset builder. - name: Account description: >- Read and update the account that owns this API key — display name, active owners and admins, and subscription summary. - name: Costs description: >- Read and update every cost surface — global product overrides, shipping method, per-variant handling fees and COGS history, and per-type cost lines (order / gateway / shipping profile / variable / fixed). Mutations trigger the same per-order COGS recalculation as web-UI changes. - name: Products description: Browse products + variants in the configured catalog. - name: Events description: Send server-side tracking events directly from your backend. paths: /accounts/api/costs/lines: post: tags: - Costs summary: Add a cost line description: | Add a new cost line for one of the five line-typed cost surfaces — `order`, `gateway`, `shipping` (profile rule), `variable`, or `fixed`. The server assigns a ULID for the new line. The `line` body is discriminated by `costType` — see the per-type schemas (`OrderCostLine`, `GatewayCostLine`, `ShippingProfileCostLine`, `VariableCostLine`, `FixedCostLine`) for the shape required by each. Triggers a per-order COGS recalculation downstream — except for `variable` and `fixed`, which apply at aggregate report time and do not require per-order recalc. **Required scope:** `costs:write`. operationId: addCostLine requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AddCostLineRequest' examples: variableAdSpend: summary: 'Variable: 2% of ad spend, marketing' value: costType: variable line: name: Google Ads — % of spend type: pct_ad_spend percentRate: 2 category: marketing channel: online currency: USD gateway: summary: 'Gateway: Shopify Payments — 2.9% + $0.30' value: costType: gateway line: name: Shopify Payments gatewayName: shopify_payments flatAmount: 0.3 percentRate: 2.9 currency: USD fixedMonthly: summary: 'Fixed: $500/month SaaS' value: costType: fixed line: name: Klaviyo subscription flatAmount: 500 frequencyUnit: month frequencyInterval: 1 category: opex currency: USD responses: '200': description: The updated cost config (with the new line appended). content: application/json: schema: type: object required: - config properties: config: type: object '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' components: schemas: AddCostLineRequest: type: object required: - costType - line description: | `line` shape is discriminated by `costType` — the listed schemas for each cost type are validated server-side. Sending an `OrderCostLine` shape with `costType=variable` is rejected with 400. properties: costType: $ref: '#/components/schemas/LineCostType' line: description: One of the per-type line shapes, selected by `costType`. oneOf: - $ref: '#/components/schemas/OrderCostLine' - $ref: '#/components/schemas/GatewayCostLine' - $ref: '#/components/schemas/ShippingProfileCostLine' - $ref: '#/components/schemas/VariableCostLine' - $ref: '#/components/schemas/FixedCostLine' LineCostType: type: string enum: - order - gateway - shipping - variable - fixed description: | The five cost-line surfaces. Each value selects the corresponding line shape in the `line` (POST) or `updates` (PUT) field of the request body. OrderCostLine: type: object required: - name - type - currency - category - channel description: >- A cost line that applies per order, per line item, or as a percentage of order totals. properties: name: type: string type: $ref: '#/components/schemas/OrderCostEntryType' flatAmount: type: number description: Required for the `per_*` types. percentRate: type: number description: Required for the `pct_*` types. weightUnit: $ref: '#/components/schemas/WeightUnit' weightIntervals: type: array items: $ref: '#/components/schemas/WeightInterval' description: Required when `type=by_order_weight`. quantityIntervals: type: array items: $ref: '#/components/schemas/QuantityInterval' description: Required when `type=by_line_item_quantity` or `by_order_quantity`. currency: type: string description: ISO currency code (e.g. `USD`). category: $ref: '#/components/schemas/CostCategory' channel: $ref: '#/components/schemas/CostChannel' filters: $ref: '#/components/schemas/CostFilters' effectiveFrom: type: string description: >- ISO-8601 date this line begins applying (optional, open-ended if omitted). effectiveTo: type: string description: ISO-8601 date this line stops applying. GatewayCostLine: type: object required: - name - gatewayName - flatAmount - percentRate - currency description: >- A payment-gateway fee — typically a flat amount plus a percent rate per transaction. properties: name: type: string gatewayName: type: string description: >- Matches the gateway label on Shopify orders (e.g. `shopify_payments`, `paypal`). flatAmount: type: number percentRate: type: number currency: type: string effectiveFrom: type: string effectiveTo: type: string ShippingProfileCostLine: type: object required: - name - countries - isDefault - rateType - currency description: | A shipping-profile rule. Only applied when the global `shippingSettings.method` is `shipping_profiles`. Match by destination country + (optionally) weight tier. properties: name: type: string countries: type: array items: type: string description: ISO-3166 alpha-2 country codes the profile applies to. isDefault: type: boolean description: Fallback profile when no country matches. rateType: $ref: '#/components/schemas/ShippingRateType' flatAmount: type: number description: Required when `rateType=flat`. weightUnit: $ref: '#/components/schemas/WeightUnit' weightTiers: type: array items: $ref: '#/components/schemas/WeightInterval' description: Required when `rateType=weight_tiered`. currency: type: string effectiveFrom: type: string effectiveTo: type: string filters: $ref: '#/components/schemas/CostFilters' VariableCostLine: type: object required: - name - type - percentRate - category - channel - currency description: A cost expressed as a percentage of an external metric (e.g. ad spend). properties: name: type: string type: $ref: '#/components/schemas/VariableCostEntryType' percentRate: type: number category: $ref: '#/components/schemas/VariableCostCategory' channel: $ref: '#/components/schemas/CostChannel' currency: type: string filters: $ref: '#/components/schemas/CostFilters' effectiveFrom: type: string effectiveTo: type: string FixedCostLine: type: object required: - name - flatAmount - frequencyUnit - frequencyInterval - category - currency description: | A recurring fixed cost (e.g. a monthly SaaS subscription). Amortised across orders in the period for margin calculations. properties: name: type: string flatAmount: type: number frequencyUnit: $ref: '#/components/schemas/FrequencyUnit' frequencyInterval: type: integer minimum: 1 description: >- How many `frequencyUnit`s between occurrences (e.g. `frequencyUnit=month`, `frequencyInterval=3` → quarterly). category: $ref: '#/components/schemas/FixedCostCategory' currency: type: string effectiveFrom: type: string effectiveTo: type: string Error: type: object required: - message properties: message: type: string description: Human-readable error message. errors: type: array description: Per-field validation errors (present on 400 responses). items: type: object properties: message: type: string key: type: string path: type: array items: type: string OrderCostEntryType: type: string enum: - per_order - per_line_item - per_refund_order - per_refund_line_item - by_order_weight - by_line_item_quantity - by_order_quantity - pct_cogs - pct_shipping - pct_total_sales - pct_gross_sales - pct_net_sales WeightUnit: type: string enum: - g - kg - oz - lb WeightInterval: type: object description: A single tier in a weight-based cost table. properties: fromWeight: type: number toWeight: type: number nullable: true amount: type: number QuantityInterval: type: object description: A single tier in a quantity-based cost table. properties: fromQuantity: type: integer toQuantity: type: integer nullable: true amount: type: number CostCategory: type: string enum: - cogs - fulfillment - transaction - marketing - agency_fees - opex - other CostChannel: type: string enum: - online - pos - both CostFilters: type: object description: | Optional filters that scope when a cost line applies (e.g. only orders from a specific source). Shape mirrors the order-exclusion filter model — see the web UI's "Add filter" form for the full operator catalog. additionalProperties: true ShippingRateType: type: string enum: - flat - weight_tiered VariableCostEntryType: type: string enum: - pct_ad_spend VariableCostCategory: type: string enum: - marketing - opex FrequencyUnit: type: string enum: - day - week - month - quarter - year FixedCostCategory: type: string enum: - marketing - opex - agency_fees - other responses: BadRequest: description: Validation error. Includes an `errors` array with per-field detail. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: >- Missing or invalid `x-api-key` / `x-pixel-id`, or key is revoked/expired. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- API key does not carry the required scope for this endpoint, or body `pixelId` does not match the `x-pixel-id` header. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The addressed resource does not exist (or belongs to a different pixel). content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: Your Upstack API key. Starts with `upstack_`. pixelId: type: apiKey in: header name: x-pixel-id description: The pixel id the request targets. ````