> ## Documentation Index
> Fetch the complete documentation index at: https://docs.global-e.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Calculate billing summary (Subscription Manager to Global-e)

> Subscription Manager calls Global-e to calculate the recurring billing summary - the selected shipping option (physical / hybrid subscriptions) and duties and taxes

<Note>
  Part of the [Subscription Connector](/subscription-connector) integration guide — see it for when and how to use this endpoint.
</Note>


## OpenAPI

````yaml api-reference/specs/billingsummarycalculate.yaml POST /subscriptions/billing-summary/calculate
openapi: 3.0.3
info:
  title: Billing Summary Calculation
  version: '1.4'
  description: >-
    This endpoint allows the Subscription Manager to request a billing summary
    calculation before processing recurring payments: for physical / hybrid
    subscriptions Global-e selects the shipping option for the next recurring
    order and returns it together with the recalculated duties and taxes
    (including shipping-based taxes); for digital-only subscriptions the
    response contains the duties and taxes breakdown.
servers:
  - url: https://{globale_api_domain}
    variables:
      globale_api_domain:
        default: globale_api_domain
        description: Global-e API host, supplied to the merchant by Global-e.
security: []
tags:
  - name: Billing summary
    x-page-title: Calculate billing summary
  - name: 'Direction: Subscription Manager → Global-e'
  - name: 'Domain: Payments'
paths:
  /subscriptions/billing-summary/calculate:
    post:
      tags:
        - Billing summary
      summary: Calculate billing summary
      description: >-
        Subscription Manager calls Global-e to calculate the recurring billing
        summary - the selected shipping option (physical / hybrid subscriptions)
        and duties and taxes
      operationId: calculateBillingSummary
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: >-
            Unique identifier for the request; the same value must be sent on
            retries so the operation is applied at most once.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingSummaryRequest'
            example:
              subscriptionId: '123456'
              merchantGuid: '1234567890'
              currencyCode: USD
              products:
                - code: PROD-001
                  quantity: 2
                  price: 149.99
              shippingAmount: 5
      responses:
        '200':
          description: >-
            Billing summary - selected shipping option and duties and taxes
            values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingSummaryCalculationResponse'
              examples:
                physical_subscription:
                  summary: Physical / hybrid - shipping option returned
                  value:
                    externalReference: req-7890
                    selectedShippingOption:
                      optionId: '1042'
                      name: DHL Standard
                      price: 6.99
                      currencyCode: USD
                    dtResults:
                      - deliveryId: '0'
                        shippingServiceCode: STD-SHMID
                        status:
                          isSuccessful: true
                        lineItems:
                          - index: '111'
                            code: item-001
                            hsCode: '123456'
                            dutyLines:
                              - name: Import Duty
                                price: 2
                                rate: 0.02
                            taxLines:
                              - name: Sales Tax
                                price: 1.5
                                rate: 0.1
                        shipping:
                          taxLines:
                            - name: Sales Tax
                              price: 1.5
                              rate: 0.1
                        additionalFees:
                          - name: Formal Clearance Fee
                            price: 15
                        totals:
                          taxes: 3
                          duties: 2
                          additionalFees: 15
                    fxRates:
                      - fxRate: 3.75
                        fxMarginRate: 1.02
                        fxRateServiceProviderId: 5
                        currencyFrom: ILS
                        currencyTo: USD
                digital_only_subscription:
                  summary: Digital-only - no selectedShippingOption returned
                  value:
                    externalReference: req-7890
                    dtResults:
                      - deliveryId: '0'
                        status:
                          isSuccessful: true
                        lineItems:
                          - index: '111'
                            code: item-001
                            hsCode: '123456'
                            dutyLines: []
                            taxLines:
                              - name: Sales Tax
                                price: 1.5
                                rate: 0.1
                        additionalFees: []
                        totals:
                          taxes: 1.5
                          duties: 0
                          additionalFees: 0
                calculation_failed:
                  summary: Delivery over the formal clearance threshold
                  value:
                    externalReference: req-7890
                    dtResults:
                      - deliveryId: '0'
                        status:
                          isSuccessful: false
                          error:
                            code: 1
                            description: >-
                              Delivery total is above
                              OverformalClearanceThreshold
                        lineItems: []
                        additionalFees: []
                        totals:
                          taxes: 0
                          duties: 0
                          additionalFees: 0
        '400':
          description: Bad Request - Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_order_id:
                  summary: Invalid Order ID
                  value:
                    error: Invalid OrderId format
                    code: INVALID_ORDER_ID
                    description: The provided OrderId is not in the correct format.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  summary: Unauthorized
                  value:
                    error: Invalid API Key
                    code: UNAUTHORIZED
                    description: Invalid API Key
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                insufficient_permissions:
                  summary: Insufficient permissions
                  value:
                    error: Access denied
                    code: INSUFFICIENT_PERMISSIONS
                    description: User does not have permission to perform the operation.
        '404':
          description: Object not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                subscription_details_not_found:
                  summary: Subscription details not found
                  value:
                    error: Subscription details not found
                    code: SUBSCRIPTION_DETAILS_NOT_FOUND
                    description: >-
                      No subscription details found for the specified
                      subscriptionId.
                product_not_found:
                  summary: Product not found
                  value:
                    error: Product not found
                    code: PRODUCT_NOT_FOUND
                    description: No product found for the specified code.
        '409':
          description: Conflict - Idempotency key conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                idempotency_key_conflict:
                  summary: Idempotency key conflict
                  value:
                    error: Idempotency key conflict
                    code: IDEMPOTENCY_KEY_CONFLICT
                    description: >-
                      Request already in use. Use a different Idempotency-Key
                      for new operation.
        '422':
          description: Unprocessable Content - the request is valid but cannot be fulfilled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                no_shipping_option_available:
                  summary: No shipping option available
                  value:
                    error: No shipping option available
                    code: NO_SHIPPING_OPTION_AVAILABLE
                    description: >-
                      No shipping option could be selected for the
                      subscription's destination.
                products_restricted:
                  summary: One or more products cannot be shipped to the destination
                  value:
                    error: Product restricted for destination
                    code: PRODUCT_RESTRICTED
                    description: >-
                      SKU-002: This product cannot be shipped to your location.
                      SKU-008: This product cannot be shipped to your location.
                      SKU-009: This product cannot be shipped to your location.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    error: Internal server error
                    code: INTERNAL_ERROR
                    description: An unexpected error occurred while processing the request.
        default:
          description: General error structure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
        - lang: curl
          source: >-
            curl -X POST
            "https://{globale_api_domain}/subscriptions/billing-summary/calculate"
            \
              -H "Authorization: Bearer {JWT Token}" \
              -H "Idempotency-Key: 3f1a7c2e-9b40-4d6f-8a21-5c9e0b7d4a11" \
              -H "Content-Type: application/json" \
              -d '{"subscriptionId":"123456","merchantGuid":"1234567890","currencyCode":"USD","products":[{"code":"PROD-001","quantity":2,"price":149.99}]}'
components:
  schemas:
    BillingSummaryRequest:
      type: object
      required:
        - subscriptionId
        - merchantGuid
        - currencyCode
        - products
      properties:
        subscriptionId:
          $ref: '#/components/schemas/SubscriptionId'
        merchantGuid:
          $ref: '#/components/schemas/MerchantGuid'
        currencyCode:
          $ref: '#/components/schemas/CurrencyCode'
        products:
          $ref: '#/components/schemas/ProductsDutiesAndTaxes'
        discounts:
          allOf:
            - $ref: '#/components/schemas/Discounts'
          description: Applied discounts for this cycle; not persisted on the subscription.
        shippingAmount:
          type: number
          format: double
          minimum: 0
          description: >-
            Shipping amount charged to the shopper for this cycle. 0 means free
            shipping; omit to let Global-e price it
    BillingSummaryCalculationResponse:
      type: object
      required:
        - externalReference
        - dtResults
      properties:
        externalReference:
          type: string
          maxLength: 50
          description: Unique identifier for the request
        selectedShippingOption:
          allOf:
            - $ref: '#/components/schemas/ShippingOption'
          description: >-
            Shipping option selected for the recurring order (physical / hybrid
            subscriptions). Not returned for digital-only subscriptions.
        dtResults:
          type: array
          description: Array of duty/tax calculation results
          items:
            $ref: '#/components/schemas/DtResult'
        fxRates:
          type: array
          description: Foreign exchange rates used in calculations
          items:
            $ref: '#/components/schemas/FxRate'
    ErrorResponse:
      type: object
      description: Error response structure
      required:
        - error
        - code
      properties:
        error:
          type: string
          description: Human-readable error message
        code:
          type: string
          description: >-
            Machine-readable error code. Codes documented for the Subscriptions
            integration:


            | Code | HTTP status | Description | Typical cause |

            | --- | --- | --- | --- |

            | INVALID_ORDER_ID | 400 | Invalid order ID format | Malformed order
            ID |

            | INVALID_SUBSCRIPTION_ID | 400 | Invalid subscription ID |
            Malformed subscription ID |

            | INVALID_PRODUCT_CODE | 400 | Invalid product code | Unknown
            product code |

            | UNAUTHORIZED | 401 | Authentication failed | Invalid or missing
            credentials |

            | INSUFFICIENT_PERMISSIONS | 403 | Insufficient permissions | User
            lacks required permissions |

            | ORDER_NOT_FOUND | 404 | Order not found | Order ID doesn't exist |

            | SUBSCRIPTION_NOT_FOUND | 404 | Subscription not found |
            Subscription ID doesn't exist |

            | SUBSCRIPTION_DETAILS_NOT_FOUND | 404 | Subscription details not
            found | Details not found in Global-e |

            | PRODUCT_NOT_FOUND | 404 | Product not found | Product code doesn't
            exist |

            | EXTERNAL_REFERENCE_NOT_FOUND | 404 | External reference not found
            | Invalid externalReferenceId |

            | IDEMPOTENCY_KEY_CONFLICT | 409 | Idempotency key conflict |
            Duplicate idempotency key |

            | NO_SHIPPING_OPTION_AVAILABLE | 422 | No shipping option available
            | No shipping option for the subscription's destination |

            | INVALID_ADDRESS | 422 | Shipping address failed validation |
            Address failed validation on address update |

            | COUNTRY_CHANGE_NOT_ALLOWED | 422 | Country change rejected | The
            shipping address country cannot be changed |

            | VALIDATION_FAILED | 422 | Validation failed | Missing/invalid
            field |

            | INTERNAL_ERROR | 500 | Internal server error | Unexpected server
            error |
        description:
          type: string
          description: Detailed error description
    SubscriptionId:
      type: string
      maxLength: 100
      description: Unique identifier of subscription in the subscription manager.
    MerchantGuid:
      type: string
      format: uuid
      description: Global-e merchant unique identifier
    CurrencyCode:
      type: string
      description: ISO 4217 currency code
      pattern: ^[A-Z]{3}$
    ProductsDutiesAndTaxes:
      type: array
      description: List of products
      minItems: 1
      items:
        type: object
        description: Fields which describe a product
        required:
          - code
          - quantity
          - price
        properties:
          code:
            $ref: '#/components/schemas/ProductCode'
          quantity:
            $ref: '#/components/schemas/ProductQuantity'
          price:
            $ref: '#/components/schemas/ProductPrice'
    Discounts:
      type: array
      description: Applied discounts (order and product level)
      items:
        $ref: '#/components/schemas/Discount'
    ShippingOption:
      type: object
      description: >-
        The single shipping option selected for the recurring order, matched to
        the subscription's first-order shipping method with a deterministic
        fallback
      required:
        - optionId
        - name
        - price
        - currencyCode
      properties:
        optionId:
          type: string
          maxLength: 50
          description: Identifier of the selected shipping option
        name:
          type: string
          maxLength: 100
          description: Display name of the shipping service
        price:
          type: number
          format: double
          minimum: 0
          description: Cost of the shipping option in the requested currency
        currencyCode:
          $ref: '#/components/schemas/CurrencyCode'
    DtResult:
      type: object
      required:
        - deliveryId
        - status
        - lineItems
        - additionalFees
        - totals
      properties:
        deliveryId:
          type: string
          maxLength: 50
          description: Delivery identifier. Always "0"
        shippingServiceCode:
          type: string
          maxLength: 50
          description: Shipping service code
        status:
          $ref: '#/components/schemas/Status'
        lineItems:
          type: array
          description: Array of line items with duties/taxes
          items:
            $ref: '#/components/schemas/LineItem'
        shipping:
          $ref: '#/components/schemas/Shipping'
        additionalFees:
          type: array
          description: Additional fees (e.g. clearance)
          items:
            $ref: '#/components/schemas/AdditionalFee'
        totals:
          $ref: '#/components/schemas/Totals'
    FxRate:
      type: object
      required:
        - fxRate
        - fxMarginRate
        - fxRateServiceProviderId
        - currencyFrom
        - currencyTo
      properties:
        fxRate:
          type: number
          description: Exchange rate
        fxMarginRate:
          type: number
          description: Margin rate coefficient
        fxRateServiceProviderId:
          type: integer
          description: Rate provider ID
        currencyFrom:
          type: string
          maxLength: 3
          description: Source currency (ISO 3)
        currencyTo:
          type: string
          maxLength: 3
          description: Target currency (ISO 3)
    ProductCode:
      type: string
      description: Unique product identifier
    ProductQuantity:
      type: integer
      format: int32
      description: Products quantity value.
    ProductPrice:
      type: number
      format: double
      description: Product price
    Discount:
      type: object
      properties:
        code:
          type: string
          description: Discount code
        type:
          type: string
          enum:
            - Cart
          description: >-
            Discount type. Only "Cart" is supported, for both cart-level and
            product-level discounts; any other value is rejected with 400
            VALIDATION_FAILED
        amount:
          type: number
          format: double
          description: Discount amount, greater than 0
        productCode:
          type: string
          nullable: true
          description: null for order-level, productCode for product-level
    Status:
      type: object
      description: Calculation status (isSuccessful, error)
      required:
        - isSuccessful
      properties:
        isSuccessful:
          type: boolean
          description: Status success
        error:
          type: object
          description: Error details
          required:
            - code
            - description
          properties:
            code:
              type: integer
              description: Error code
            description:
              type: string
              maxLength: 500
              description: Error description
    LineItem:
      type: object
      required:
        - index
        - code
        - hsCode
        - dutyLines
        - taxLines
      properties:
        index:
          type: string
          maxLength: 50
          description: Item index
        code:
          type: string
          maxLength: 50
          description: Product code
        hsCode:
          type: string
          maxLength: 10
          description: Harmonized System code
        dutyLines:
          type: array
          description: Array of duty lines
          items:
            $ref: '#/components/schemas/DutyLine'
        taxLines:
          type: array
          description: Array of tax lines
          items:
            $ref: '#/components/schemas/TaxLine'
    Shipping:
      type: object
      description: Shipping tax lines
      required:
        - taxLines
      properties:
        taxLines:
          type: array
          description: Shipping taxes
          items:
            $ref: '#/components/schemas/TaxLine'
    AdditionalFee:
      type: object
      required:
        - name
        - price
      properties:
        name:
          type: string
          maxLength: 100
          description: Name
        price:
          type: number
          description: Price
    Totals:
      type: object
      description: Total breakdown (taxes, duties, fees)
      required:
        - taxes
        - duties
        - additionalFees
      properties:
        taxes:
          type: number
          description: Total taxes paid by customer
        duties:
          type: number
          description: Total duties paid by customer
        additionalFees:
          type: number
          description: Total additional fees paid by customer
    DutyLine:
      type: object
      required:
        - name
        - price
      properties:
        name:
          type: string
          maxLength: 100
          description: Name
        price:
          type: number
          description: Price
        rate:
          type: number
          description: Rate
    TaxLine:
      type: object
      required:
        - name
        - price
        - rate
      properties:
        name:
          type: string
          maxLength: 100
          description: Name
        price:
          type: number
          description: Price
        rate:
          type: number
          description: Rate

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.