From 212c70d5eebc96a142ab61aa08298be6d7e90ca0 Mon Sep 17 00:00:00 2001 From: Shawn Wang <94653751+bc-shawnwang@users.noreply.github.com> Date: Mon, 16 Dec 2024 09:35:45 +1100 Subject: [PATCH] doc(checkout): CHECKOUT-8739 update doc to reflect new feature of order level fees. (#642) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # [CHECKOUT-8739](https://bigcommercecloud.atlassian.net/browse/CHECKOUT-8739) ## What changed?

bulk Fees APIs

 v3 checkout api changes: Have 3 endpoints to support bulk operations on fees: - POST v3/checkouts/:checkoutId/fees - PUT v3/checkouts/:checkoutId/fees - DELETE v3/checkouts/:checkoutId/fees storefront checkout api: - response of checkout object added applied fees (fees:) ### Overall ![image](https://github.com/user-attachments/assets/b4164b80-0d1c-42f5-a2d9-c780cf1d15e0) ### bulk POST ![image](https://github.com/user-attachments/assets/c37b721a-736f-4a34-b03d-320631f3fff0) ### bulk PUT Screenshot 2024-11-28 at 10 11 24 AM ### bulk DELETE ![image](https://github.com/user-attachments/assets/65d20c64-6f50-401f-994a-7eab883b4e18)
## Release notes draft * The newly-released custom order level fees on the checkout is now available to use. Now, you’ll be able to apply and manage the checkout's order level fees via v3 management api, and fetch any checkout's applied fees on storefront checkout api and v3 management checkout api. ## Anything else? ping @bigcommerce/team-checkout @bigcommerce/dev-docs [CHECKOUT-8739]: https://bigcommercecloud.atlassian.net/browse/CHECKOUT-8739?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ --- reference/checkouts.sf.yml | 52 ++++++++- reference/checkouts.v3.yml | 234 +++++++++++++++++++++++++++++++++++++ 2 files changed, 284 insertions(+), 2 deletions(-) diff --git a/reference/checkouts.sf.yml b/reference/checkouts.sf.yml index 4bf03192f..80747274e 100644 --- a/reference/checkouts.sf.yml +++ b/reference/checkouts.sf.yml @@ -898,7 +898,15 @@ components: discountedAmount: 5 displayName: $5.00 off the order total id: 1 - customer: + fees: + - id: 497f6eca-6276-4993-bfeb-53cbbbba6f08 + type: custom_fee + name: AAINS + displayName: Package Protection Insurance + cost: 12.02 + source: AA + taxClassId: 12 + customer: addresses: [{}] customerGroup: id: 1 @@ -965,6 +973,11 @@ components: description: Coupons applied at the checkout level. items: $ref: '#/components/schemas/CheckoutCoupon' + fees: + type: array + description: Fees applied at the checkout level. + items: + $ref: '#/components/schemas/CheckoutFee' createdTime: type: string description: Time when the cart was created. @@ -1134,7 +1147,42 @@ components: type: number description: The discounted amount applied within a given context. format: double - Customer: + CheckoutFee: + title: Checkout Fee + type: object + properties: + id: + type: string + format: uuid + description: The fee ID. + example: 497f6eca-6276-4993-bfeb-53cbbbba6f08 + type: + type: string + description: The type of the fee. + enum: + - custom_fee + name: + type: string + description: Name of the fee. + example: AAINS + displayName: + type: string + description: Display name of the fee targeting customers/shoppers. + example: Package Protection Insurance + cost: + type: number + description: Cost of the fee (include or exclude tax dependent on tax settings, same as shipping cost). + example: 10.0 + source: + type: string + description: The source of the request. + example: AA + taxClassId: + type: integer + description: The tax class ID. + example: 1 + x-internal: false + Customer: type: object description: Customer details. properties: diff --git a/reference/checkouts.v3.yml b/reference/checkouts.v3.yml index 4a7d8ea96..ccb2a6843 100644 --- a/reference/checkouts.v3.yml +++ b/reference/checkouts.v3.yml @@ -27,6 +27,7 @@ tags: - name: Checkout Orders - name: Checkout Settings - name: Checkout Token + - name: Checkout Fees security: - X-Auth-Token: [] paths: @@ -7764,6 +7765,102 @@ paths: meta: {} '409': $ref: '#/components/responses/CartConflictErrorResponse' + '/checkouts/{checkoutId}/fees': + post: + tags: + - Checkout Fees + summary: Add order level fees to a checkout + description: |- + Adds order level fees to a checkout. + + Limits: + - Maximum of 5 fees per checkout. + operationId: CheckoutsFeesByCheckoutIdPost + parameters: + - $ref: '#/components/parameters/checkoutId' + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/Content-Type' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddFeesRequest' + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Checkout' + meta: + $ref: '#/components/schemas/MetaOpen' + x-unitTests: [] + x-operation-settings: + CollectParameters: false + AllowDynamicQueryParameters: false + AllowDynamicFormParameters: false + IsMultiContentStreaming: false + x-codegen-request-body-name: body + put: + tags: + - Checkout Fees + summary: Update order level fees in a checkout + description: |- + Updates order level fees in a checkout. + > We do not support partial updates, so please send the total entity values for each fee to be updated. + operationId: CheckoutsFeesByCheckoutIdPut + parameters: + - $ref: '#/components/parameters/checkoutId' + - $ref: '#/components/parameters/Accept' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateFeesRequest' + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Checkout' + meta: + $ref: '#/components/schemas/MetaOpen' + delete: + tags: + - Checkout Fees + summary: Delete order level fees from a checkout. + description: Delete fees from a checkout. + operationId: CheckoutsFeesByCheckoutIdDelete + parameters: + - $ref: '#/components/parameters/checkoutId' + - $ref: '#/components/parameters/Accept' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteFeesRequest' + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Checkout' + meta: + $ref: '#/components/schemas/MetaOpen' '/checkouts/{checkoutId}/orders': post: tags: @@ -8655,6 +8752,11 @@ components: description: Coupons applied at checkout level. items: $ref: '#/components/schemas/AppliedCoupon' + fees: + type: array + description: Fees applied at the checkout level. + items: + $ref: '#/components/schemas/CheckoutFee' order_id: type: string description: '' @@ -8767,6 +8869,46 @@ components: format: float example: 0.9 x-internal: false + CheckoutFee: + title: Checkout Fee + type: object + properties: + id: + type: string + format: uuid + description: The fee ID. + example: 497f6eca-6276-4993-bfeb-53cbbbba6f08 + type: + type: string + description: The type of the fee. + enum: + - custom_fee + name: + type: string + description: Name of the fee. + example: AAINS + display_name: + type: string + description: Display name of the fee targeting customers/shoppers. + example: Package Protection Insurance + cost_inc_tax: + type: number + description: Cost of the fee including tax. + example: 10.0 + cost_ex_tax: + type: number + description: Cost of the fee excluding tax. + example: 9.9 + source: + type: string + description: The source of the request. + example: AA + tax_class_id: + type: integer + nullable: true + description: The tax class ID. + example: 1 + x-internal: false AddressProperties: title: Address Properties required: @@ -9047,6 +9189,98 @@ components: description: The cart version that you expect to apply the updates. If the provided version doesn't match the current cart version, you will receive a conflict error. This field is optional; if not provided, optimistic concurrency control will not apply. example: 1 x-internal: false + BaseFee: + type: object + required: + - type + - name + - display_name + - cost + - source + properties: + type: + type: string + description: The type of the fee. + enum: + - custom_fee + name: + type: string + minLength: 1 + maxLength: 50 + description: The name of the fee. + example: AAINS + display_name: + type: string + minLength: 1 + maxLength: 200 + description: The display name of the fee targeting customers/shoppers. + example: Package Protection Insurance + cost: + type: number + description: The cost of the fee. + example: 7.12 + source: + type: string + minLength: 1 + maxLength: 50 + description: The source of the request. + example: AA + tax_class_id: + type: integer + description: The tax class ID applied to this fee (you can retrieve the tax class ID from our management API - v2/tax_classes). If the tax class is not provided or is null, the tax class set in the control panel is applied. + example: 1 + FeeWithId: + allOf: + - $ref: '#/components/schemas/BaseFee' + - type: object + properties: + id: + type: string + description: ID of the fee. + example: 3c26f3e6-146d-4dce-8159-2a77c0bba409 + required: + - id + AddFeesRequest: + title: Fees POST request + type: object + required: + - fees + properties: + fees: + type: array + description: The fees to be added to a checkout. + items: + $ref: '#/components/schemas/BaseFee' + minItems: 1 + x-internal: false + UpdateFeesRequest: + title: Fees PUT request + type: object + required: + - fees + properties: + fees: + type: array + description: The fees to be updated in a checkout. + items: + $ref: '#/components/schemas/FeeWithId' + minItems: 1 + x-internal: false + DeleteFeesRequest: + title: Fees DELETE request + type: object + required: + - ids + properties: + ids: + type: array + description: The IDs of the fees to be deleted from a checkout. + items: + type: string + description: The ID of the fee. + example: 3c26f3e6-146d-4dce-8159-2a77c0bba409 + minItems: 1 + x-internal: false DeleteCouponCodeRequest: title: Delete Coupon Request type: object