7.1 KiB
order Specification
Purpose
Checkout splitting a cart into per-shop orders, plus order lifecycle and ownership.
Requirements
Requirement: Checkout splits by shop
POST /api/orders/checkout SHALL create one order per distinct shop in the cart, in a single database transaction: stock decrement, order + item insert with price snapshots, cart clear, active flash-sale resolution when no group-buy intent applies to the SKU, requested group-buying intent validation, and requested coupon redemption when eligible. All amounts use the cart's SKU currencies converted into the buyer-chosen display currency at checkout time. A group-buy intent SHALL contain exactly one active activity SKU at quantity 1 and either an open group identifier or a request to open a group; the server SHALL snapshot the group price and group identity on the resulting pending-payment order. Group intent SHALL return 409 when that SKU is also eligible for an overlapping flash sale. For each remaining cart line without group intent the server SHALL resolve an eligible active flash-sale item as specified by flash-sales, snapshot the final unit price and activity identity, and charge standard price for ineligible quantity. The request MAY select at most one owned coupon per generated shop order; the server SHALL persist coupon_id, discount_minor, and post-discount total_minor only after ownership, shop, status, window, and threshold validation. The client SHALL NOT provide a discount amount. The server SHALL reject a coupon (409) for any shop order that applied flash-sale pricing or carries group-buy intent.
Scenario: two shops → two orders
- WHEN the cart contains SKUs from shops A and B without group-buy intent
- THEN two orders are created, each with only its shop's items, and the cart is empty
Scenario: insufficient stock
- WHEN any line's qty exceeds SKU stock or applicable flash-sale stock
- THEN the whole checkout returns 409 and no order is created and stock is unchanged
Scenario: active flash price applied
- WHEN checkout contains a SKU with an active eligible flash-sale item and no group-buy intent applies to it
- THEN the order item records the server-calculated flash-sale price and activity identity
Scenario: coupon rejected on a flash-priced shop order
- WHEN the customer selects a coupon for a shop whose generated order applied flash-sale pricing on any line
- THEN checkout returns 409 and creates no orders
Scenario: open a group at checkout
- WHEN a customer checks out one eligible group-buying SKU at quantity 1 with open-group intent
- THEN a pending-payment order and an open group identity are created with the server-resolved group price
Scenario: coupon rejected on a group shop order
- WHEN the customer selects a coupon for the shop that carries group-buy intent
- THEN checkout returns 409 and creates no orders
Scenario: coupon applies to one matching shop
- WHEN the customer selects an eligible shop coupon and that shop's generated order has no flash-priced lines and no group-buy intent
- THEN the order records that coupon and its server-calculated discount
Requirement: Order lifecycle
Status transitions SHALL be: pending_payment → paid → fulfilling → shipped → completed; cancellable only from pending_payment, which MUST restore SKU stock, any reserved flash-sale activity stock consumed by the order, and a redeemed coupon to claimed status when the order has one. Pending-payment cancellation SHALL NOT change group paid-member counts. When the cancelled order opened the group and paid member count is zero, the group SHALL become cancelled. Payment of an order with group-buying intent SHALL also validate and atomically claim an open group seat; full, expired, or cancelled groups SHALL return 409 and leave the order pending_payment.
Scenario: group payment wins final seat
- WHEN payment fills the final available group seat
- THEN the payment succeeds and the group state becomes successful
Scenario: cancel restores stock
- WHEN a customer cancels a pending_payment group-intent order
- THEN SKU stock increases by the ordered qty, status is cancelled, and no paid group membership is removed
Scenario: unpaid opener cancel closes an empty group
- WHEN the opening pending_payment order is cancelled and the group has zero paid members
- THEN the group status becomes cancelled and a later payment against that group returns 409
Scenario: cancel restores coupon
- WHEN a customer cancels a pending_payment order with a redeemed coupon
- THEN the coupon is detached from the order and becomes claimed
Scenario: illegal transition rejected
- WHEN cancelling a paid order via the customer endpoint
- THEN the API returns 409
Requirement: Order ownership
Customers SHALL see only their own orders; shop roles only their shop's orders; platform_admin sees all.
Scenario: cross-customer read denied
- WHEN customer X requests customer Y's order id
- THEN the API returns 404
Requirement: Order aftersale eligibility and refund summary
Order and order-item responses SHALL expose the configured after-sale deadline after confirmation of delivery, whether each line has an active aftersale, its remaining refundable integer minor-unit amount, and the order's authoritative refund_total_minor. The API SHALL allow applications for paid or shipped orders while the configured window is open, and SHALL reject new applications after the deadline. The refund summary SHALL be sourced from completed aftersales records and updated only by a guarded refund-completion transaction.
Scenario: confirmed order remains eligible during the window
- WHEN a customer views a completed order before the configured N-day after-sale window expires
- THEN the order detail includes an after-sale deadline and each refundable line exposes its remaining amount and application action
Scenario: expired window hides the action
- WHEN the configured after-sale deadline has passed
- THEN the order and item responses mark after-sale unavailable and an application returns 409
Scenario: order refund total is authoritative
- WHEN an aftersale completes a refund
- THEN the order response's
refund_total_minorequals the sum of completed aftersale amounts and is not client-calculated
Requirement: Order item ownership and state safety
After-sale eligibility SHALL resolve the order item through the authenticated customer's order ownership (or the owning shop's own_shop scope for merchant actions), and every refund total update SHALL use a conditional status/amount guard so concurrent completions cannot refund more than the paid order amount.
Scenario: cross-customer item is hidden
- WHEN a customer submits another customer's order item id
- THEN the API returns 404 without disclosing order or refund data
Scenario: concurrent refunds stay within paid amount
- WHEN concurrent aftersales would make completed refunds exceed the line or order paid amount
- THEN the guarded update rejects the excess completion and stored refund totals remain within the paid amount