openapi: 3.0.1
info:
  title: Customs API
  version: '1.0'
servers:
  - url: https://api.bring.com/customs/v1

security:
  - mybringApiUid: []
    mybringApiKey: []

paths:
  /declarations:
    post:
      summary: Submit customs declaration for a shipment
      parameters:
        - in: header
          name: X-Bring-Test-Indicator
          schema:
            type: boolean
          required: true
          description: >
            Indicates whether this is a test message or a live one.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomsDeclarationDto'
            examples:

              single:
                summary: Send customs declaration for Business Pallet (0336)
                value:
                  customerNumber: "1234567890"
                  currencyCode: SEK
                  declarationType: "EXPORT_IMPORT"
                  shipment:
                    consignmentId: "012345678910"
                    service: "0336"
                    termsOfDelivery:
                      incotermsCode: DDP
                      location: Oslo
                    freightCost: 1000.50
                    insuranceCost: 5000.50
                  importer:
                    name: Im Porter
                    addressLine1: Importer street 42
                    postalCode: "12000"
                    city: Stockholm
                    countryCode: "SE"
                    id: "1234567891"
                  exporter:
                    name: Ex Porter
                    addressLine1: Exporter street 42
                    postalCode: "1234"
                    city: Oslo
                    countryCode: "NO"
                    id: null
                  invoices:
                    - invoiceNumber: "401528"
                      invoiceDate: 2025-11-13
                      amount: 100887.50
                      discount: 250.50
                    - invoiceNumber: "401529"
                      invoiceDate: 2025-11-14
                      amount: 100887.50
                  customsDeclarations:
                    - consignmentItemId: CS128104136NO
                      quantityOtherUnit: 2
                      goodsDescription: description 1
                      customsArticleNumber: article number 1
                      grossWeight: 1.0
                      netWeight: 1.0
                      amount: 1500.50
                      countryCodeOrigin: SE
                      tradePreferenceCode: "A"
                    - consignmentItemId: CS128104137NO
                      numberOfPieces: 3
                      goodsDescription: description 2
                      customsArticleNumber: article number 2
                      grossWeight: 2.0
                      netWeight: 2.0
                      amount: 250.50
                      countryCodeOrigin: FI
                      salesOrder:
                        orderNumber: OPT5566
                        articleNumber: GK153-1
                      documentReferences:
                        - certificateCode: SE/HF/003245

              single_0342_norway_sweden:
                summary: Customs declaration for Pickup Parcel Bulk (0342) from Norway to Sweden
                value:
                  customerNumber: "1234567890"
                  currencyCode: SEK
                  declarationType: "EXPORT_IMPORT"
                  shipment:
                    consignmentId: "012345678910"
                    service: "0342"
                    termsOfDelivery:
                      incotermsCode: DAP
                      location: Stockholm
                    freightCost: 1000.50
                    insuranceCost: 5000.50
                  importer:
                    name: Im Porter
                    addressLine1: Importer street 42
                    postalCode: "12000"
                    city: Stockholm
                    countryCode: "SE"
                    id: "1234567891"
                  exporter:
                    name: Ex Porter
                    addressLine1: Exporter street 42
                    postalCode: "1234"
                    city: Oslo
                    countryCode: "NO"
                    vatId: VAT number
                    id: null
                  recipient:
                    name: Recipient
                    addressLine1: Recipient street 42
                    postalCode: "12001"
                    city: Stockholm
                    countryCode: "SE"
                    id: null
                  shipTo:
                    name: Delivering too
                    addressLine1: Delivery street 42
                    postalCode: "12001"
                    city: Stockholm
                    countryCode: SE
                    id: null
                  invoices:
                    - invoiceNumber: "401528"
                      invoiceDate: 2025-11-13
                      amount: 100887.50
                      discount: 250.50
                    - invoiceNumber: "401529"
                      invoiceDate: 2025-11-14
                      amount: 100887.50
                  customsDeclarations:
                    - consignmentItemId: 123456
                      quantityOtherUnit: 2
                      goodsDescription: description 1
                      customsArticleNumber: article number 1
                      grossWeight: 1.0
                      netWeight: 1.0
                      amount: 1500.50
                      countryCodeOrigin: NO
                      tradePreferenceCode: "A"
                    - consignmentItemId: 1234567
                      numberOfPieces: 3
                      goodsDescription: description 2
                      customsArticleNumber: article number 2
                      grossWeight: 2.0
                      netWeight: 2.0
                      amount: 250.50
                      countryCodeOrigin: NO
                      salesOrder:
                        orderNumber: OPT5566
                        articleNumber: GK153-1
                      documentReferences:
                        - certificateCode: SE/HF/003245

              minimal_single_0342_norway_sweden:
                summary: Minimal customs declaration for Pickup Parcel Bulk (0342) from Norway to Sweden
                value:
                  customerNumber: "1234567890"
                  currencyCode: SEK
                  shipment:
                    consignmentId: "012345678910"
                    service: "0342"
                    termsOfDelivery:
                      incotermsCode: DAP
                      location: Stockholm
                  importer:
                    name: Im Porter
                    addressLine1: Importer street 42
                    postalCode: "12000"
                    city: Stockholm
                    countryCode: "SE"
                    vatId: VAT number
                  exporter:
                    name: Ex Porter
                    addressLine1: Exporter street 42
                    postalCode: "1234"
                    city: Oslo
                    countryCode: "NO"
                    vatId: VAT number
                  recipient:
                    name: Recipient
                    addressLine1: Recipient street 42
                    postalCode: "12001"
                    city: Stockholm
                    countryCode: SE
                  invoices:
                    - invoiceNumber: "401528"
                      invoiceDate: 2025-11-13
                      amount: 100887.50
                  customsDeclarations:
                    - consignmentItemId: 123456
                      goodsDescription: description 1
                      customsArticleNumber: tariff code 1
                      grossWeight: 1.0
                      netWeight: 1.0
                      amount: 1500.50
                      countryCodeOrigin: NO
                    - consignmentItemId: 1234567
                      numberOfPieces: 3
                      goodsDescription: description 2
                      customsArticleNumber: tariff code 2
                      grossWeight: 2.0
                      netWeight: 2.0
                      amount: 250.50
                      countryCodeOrigin: NO

              bulk:
                summary: Send customs declaration for Routing Label (0300)
                value:
                  customerNumber: "1234567890"
                  currencyCode: SEK
                  declarationType: "EXPORT_IMPORT"
                  shipment:
                    consignmentId: "012345678910"
                    service: "0300"
                    termsOfDelivery:
                      incotermsCode: DDP
                      location: Oslo
                    freightCost: 1000.50
                    insuranceCost: 5000.50
                  importer:
                    name: Im Porter
                    addressLine1: Importer street 42
                    postalCode: "12000"
                    city: Stockholm
                    countryCode: "SE"
                    id: "1234567891"
                  exporter:
                    name: Ex Porter
                    addressLine1: Exporter street 42
                    postalCode: "1234"
                    city: Oslo
                    countryCode: "NO"
                  invoices:
                    - invoiceNumber: "401528"
                      invoiceDate: 2025-11-13
                      amount: 100887.50
                      discount: 250.50
                    - invoiceNumber: "401529"
                      invoiceDate: 2025-11-14
                      amount: 100887.50
                  customsDeclarations:
                    - consignmentItemId: CS128104136NO
                      quantityOtherUnit: 2
                      goodsDescription: description 1
                      customsArticleNumber: article number 1
                      grossWeight: 1.0
                      netWeight: 1.0
                      amount: 1500.50
                      countryCodeOrigin: SE
                      salesOrder: null
                      tradePreferenceCode: "A"
                    - consignmentItemId: CS128104137NO
                      numberOfPieces: 3
                      goodsDescription: description 2
                      customsArticleNumber: article number 2
                      grossWeight: 2.0
                      netWeight: 2.0
                      amount: 250.50
                      countryCodeOrigin: FI
                      salesOrder:
                        orderNumber: OPT5566
                        articleNumber: GK153-1
                      documentReferences:
                        - certificateCode: SE/HF/003245

      responses:
        '200':
          description: Successfully submitted customs declaration for a shipment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentCustomsResponseDto'
              examples:
                this:
                  summary: Success
                  value:
                    status: ACCEPTED
                    processingId: 89257cb6-43be-4250-9a56-eb679b95ba8d
                    error: null

components:
  securitySchemes:
    mybringApiUid:
      type: apiUid
      in: header
      name: X-MyBring-API-Uid
    mybringApiKey:
      type: apiKey
      in: header
      name: X-MyBring-API-Key
  schemas:
    CustomsDeclarationDto:
      type: object
      properties:
        customerNumber:
          type: string
          description: Customer number paying for the transport
        currencyCode:
          type: string
          description: Currency code (ISO 4217) that applies to all amounts in the customs declaration
        declarationType:
          type: string
          enum:
            - IMPORT
            - EXPORT
            - EXPORT_IMPORT
          default: EXPORT_IMPORT
          description: Indicates whether the declaration should be import, export, or both. Defaults to EXPORT_IMPORT if missing.
        shipment:
          $ref: '#/components/schemas/ShipmentDto'
        exporter:
          $ref: '#/components/schemas/PartyDto'
        importer:
          $ref: '#/components/schemas/PartyDto'
        shipTo:
          $ref: '#/components/schemas/PartyDto'
        recipient:
          $ref: '#/components/schemas/PartyDto'
        invoices:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceDto'
          description: List of invoice data
        customsDeclarations:
          type: array
          items:
            $ref: '#/components/schemas/CustomsLineDto'
          description: List of customs lines
      required:
        - customerNumber
        - currencyCode
        - shipment
        - exporter
        - importer
        - invoices
        - customsDeclarations

    ShipmentCustomsResponseDto:
      type: object
      description: The result of the customs declaration
      properties:
        status:
          type: string
          enum:
            - ACCEPTED
            - FAILED
          description: The outcome of the request
        processingId:
          type: string
          description: A processing id for the request
        error:
          type: string
          description: A description of the error that occurred

    ShipmentDto:
      type: object
      description: Describes shipment data associated with the customs declaration
      properties:
        consignmentId:
          type: string
          maxLength: 35
          description: Customs consignment id for the shipment. Top level id.
        service:
          type: string
          enum:
            - '0300'
            - '0336'
            - '0342'
            - '0344'
          description: Service code declared. 0300 is the service code for bulk/routing label.
        termsOfDelivery:
          $ref: '#/components/schemas/TermsOfDeliveryDto'
        freightCost:
          type: number
          description: Cost of freight. In base units.
        insuranceCost:
          type: number
          description: Cost of insurance. In base units.
      required:
        - consignmentId
        - service
        - termsOfDelivery

    PartyDto:
      type: object
      description: Information about the shipTo(delivery), recipient, importer or exporter party
      properties:
        name:
          type: string
          description: The party's name
        postalCode:
          type: string
          description: The party's postal code
        city:
          type: string
          description: The party's city
        countryCode:
          type: string
          description: The party's ISO 3166 country code
        vatId:
          type: string
          description: The party's VAT number
        id:
          type: string
          description: The party's id. Usually a customer number.
      required:
        - name
        - postalCode
        - city
        - countryCode

    InvoicesDto:
      type: object
      properties:
        invoices:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceDto'
      required:
        - invoices

    InvoiceDto:
      type: object
      description: Information about a single invoice
      properties:
        invoiceNumber:
          type: string
          description: The invoice number
        invoiceDate:
          type: string
          description: The invoice date
        amount:
          type: number
          description: The invoice's total amount. In base units.
        discount:
          type: number
          description: The invoice's total discount. In base units.
      required:
        - invoiceNumber
        - invoiceDate
        - amount

    TermsOfDeliveryDto:
      type: object
      description: Information about terms of delivery
      properties:
        incotermsCode:
          type: string
          enum:
            - EXW
            - FCA
            - FAS
            - FOB
            - CFR
            - CIF
            - CPT
            - CIP
            - DPU
            - DAP
            - DDP
          description: The incoterms that applies for the customer's shipment
        location:
          type: string
          description: The location for the shipment
      required:
        - incotermsCode

    CustomsLineDto:
      type: object
      description: Information about a single customs line
      properties:
        numberOfPieces:
          type: number
          description: The number of pieces if multiple of the same
        quantityOtherUnit:
          type: number
          description: The quantity of the customs line if weight is not apt
        goodsDescription:
          type: string
          description: A description of the goods declared
        customsArticleNumber:
          type: string
          description: The customs article number, or tariff code
        grossWeight:
          type: number
          description: Gross weight for the shipment. In base units (kgs).
          minimum: 0.001
          example: 2.5
        netWeight:
          type: number
          description: Net weight for the shipment. In base units (kg).
          minimum: 0.001
          example: 2.5
        amount:
          type: number
          description: The value of the goods. In base units.
          example: 220.50
        countryCodeOrigin:
          type: string
          description: The customs line's origin ISO 3166 country code
        salesOrder:
          $ref: '#/components/schemas/SalesOrderDto'
        documentReferences:
          type: array
          items:
            $ref: '#/components/schemas/DocumentReferenceDto'
        consignmentItemId:
          type: string
          description: The customs consignment item id
        tradePreferenceCode:
          type: string
          enum:
            - A
            - B
            - C
            - G
            - P
            - J
            - N
          default: J
          description: The trade preference code. Defaults to J
      required:
        - goodsDescription
        - customsArticleNumber
        - grossWeight
        - netWeight
        - amount
        - countryCodeOrigin

    DocumentReferenceDto:
      type: object
      description: Information about a single document reference
      properties:
        certificateCode:
          type: string
          description: Certificate code for the customs line
        documentCode:
          type: string
          description: Document code for the customs line

    SalesOrderDto:
      type: object
      description: Information about the customer's sales order
      properties:
        orderNumber:
          type: string
          description: Order number of the sales order
        articleNumber:
          type: string
          description: Article number of the sales order
      required:
        - orderNumber
        - articleNumber