Issue an Invoice

This endpoint is used to create an invoice for a particular shipment. The request must include details about the shipment, such as the tracking number, chargeable weight, and charges. Upon successful creation, the API returns the invoice details along with a 201 Created status.

Endpoint:POST /api/v1/shipment/issueInvoice

Request

• URL: /api/v1/shipment/issueInvoice
• Method: POST
• Content-Type: application/json
• Authentication: Bearer token required in the Authorization header.

Headers:

Authorization: Bearer {jwt_token}
Content-Type: application/json

Sample Payload:

{
  "trackingNumber": "TRACK1234567890",
  "chargeableWeight": {
    "unit": "KG",
    "value": 12.5
  },
  "charges": [
    {
      "type": "Base Rate",
      "amount": {
        "currencyCode": "USD",
        "amount": 200.00
      }
    },
    {
      "type": "Fuel Surcharge",
      "amount": {
        "currencyCode": "USD",
        "amount": 50.00
      }
    }
  ],
  "invoice": {
    "invoiceNumber": "INV-987654321",
    "invoiceDate": "2024-09-13T10:00:00Z",
    "billingAccountNumber": "ACC-54321",
    "billingAccountName": "Acme Corporation",
    "totalDiscountAmount": 5.00,
    "taxAmount": 25.00,
    "totalAmountIncludingTax": 270.00,
    "currencyCode": "USD"
  }
}

Request Parameters

• trackingNumber (string): The unique tracking number associated with the shipment.
• chargeableWeight (object): The weight details of the shipment, including:
  • unit (string): The unit of measurement for the weight (e.g., KG, LB).
  • value (number): The numerical value of the weight.
• charges (array of objects): A list of charges related to the shipment, each containing:
  • type (string): The type of the charge (e.g., Base Rate, Insurance).
  • amount (object): The monetary value of the charge, including:
    • currencyCode (string): The three-letter ISO currency code (e.g., USD).
    • amount (number): The amount of money, expressed as a decimal value.
• invoice (object): Invoice details for the shipment, including:
  • invoiceNumber (string): The unique invoice number.
  • invoiceDate (string): The date of the invoice, in ISO 8601 format.
  • billingAccountNumber (string): The billing account number associated with the invoice.
  • billingAccountName (string): The name of the billing account associated with the invoice.
  • totalDiscountAmount (number): The total discount amount applied to the invoice. Must be 0 or more.
  • taxAmount (number): The tax amount applied to the invoice. Must be 0 or more.
  • totalAmountIncludingTax (number): The total amount including tax for the invoice. Must be 0 or more and greater than the TaxAmount.
  • currencyCode (string): The three-letter ISO currency code (e.g., USD).

Response

• Status: 201 Created

Sample Response:

{
  "status": "Success",
  "message": "Shipment invoice issued successfully.",
  "data": {
    "trackingNumber": "TRACK1234567890",
    "chargeableWeight": {
      "unit": "KG",
      "value": 12.5
    },
    "charges": [
      {
        "type": "Base Rate",
        "amount": {
          "currencyCode": "USD",
          "amount": 200
        }
      },
      {
        "type": "Fuel Surcharge",
        "amount": {
          "currencyCode": "USD",
          "amount": 50
        }
      }
    ],
    "invoice": {
      "invoiceNumber": "INV-987654321",
      "invoiceDate": "2024-09-13T10:00:00Z",
      "billingAccountNumber": "ACC-54321",
      "billingAccountName": "Acme Corporation",
      "totalDiscountAmount": 5.00,
      "taxAmount": 25.00,
      "totalAmountIncludingTax": 270.00,
      "currencyCode": "USD"
    }
  },
  "errors": null,
  "correlationId": "91e5bb2d-139f-4f54-8c5d-511502db3db8",
  "timestamp": "2024-09-13T06:18:04.5959128Z"
}

Response Fields

• status (string): Indicates whether the request was successful or failed. Possible values:

  • "success": The request was processed successfully.
  • "failure": The request failed due to an error.

• message (string): A human-readable statement describing the result of the request. For example:

  • "Shipment invoice issued successfully."
  • "Invalid request parameters."

• data (object, optional): Contains the data object that was submitted to the API in case of a successful request. For example, when creating a shipment, this will return the same ShipmentInvoiceDto object.

• errors (array of ErrorDto, optional): A list of detailed errors, provided when the request fails.

• correlationId (string): A unique identifier assigned to the request for tracking purposes. This is useful for troubleshooting or auditing and will be generated for every request, whether successful or not.

• timestamp (string): The date and time when the request was received and processed. The format is ISO 8601, for example: "2024-09-01T10:15:30Z".

Possible HTTP Status Codes

• 201 Created: The shipment invoice was successfully created.
• 400 Bad Request: The request payload is invalid or contains missing fields.
• 422 Unprocessable Entity: The input data validation failed.
• 500 Internal Server Error: The server encountered an error while processing the request.

Additional Notes

• Rate Limiting: The endpoint may be subject to rate limiting. If you encounter a 429 Too Many Requests error, implement exponential backoff for retries.

By following this guide, you'll be able to securely issue an invoice for a certain shipment in our platform.