--- updatedAt: 2026-09-04T18:00:37.000Z agentTools: projectIndex: https://developers.tackle.io/llms.txt --- # List billing adjustments for an agreement Returns billing adjustments for the agreement, including pending and completed requests. Results are not ordered. Filter client-side on `originalInvoiceId` or `status` if you need a subset. Each record includes `description` and, when present, `statusMessage` with details about validation failures. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "AWS Contracts", "description": "Read invoices and manage billing actions for your AWS Marketplace agreements.\n\nUse agreement-scoped endpoints to list invoices, request billing adjustments\n(refunds), request or track agreement cancellations, and submit flexible payment\nschedule charges.\n\n## Authentication\n\nSend a machine-to-machine (MTM) bearer token on every request. Exchange your\nclient ID and secret at `POST /mtm/v1/authenticate` on the Tackle platform API,\nthen send `Authorization: Bearer `.\n\nThe token scopes every request to your Tackle account.\n\n## Conventions\n\n- List endpoints return `{ \"\": [...], \"next\": \"\" }`. Page with\n `cursor` and `limit`. `next` is absent on the last page. An empty collection is a\n `200` with an empty array, not a `404`.\n- Cursors are opaque. Do not parse, construct, or persist them beyond the walk of a\n single list.\n- A sub-resource list returns `404` when the parent agreement does not exist for your\n account.\n- `null` and empty-string attributes are omitted from responses rather than sent.\n- Status and reason-code values come from AWS Marketplace. New values may appear\n without a version change, so treat these enums as open and handle unknown values\n gracefully.\n", "version": "1.0.0", "contact": { "name": "Tackle Engineering", "url": "https://developers.tackle.io" } }, "servers": [ { "url": "https://aws-agreement-api.tackle.io", "description": "Production" }, { "url": "https://aws-agreement-api.dev.tkl.sh", "description": "Development" } ], "security": [ { "tackleAuth": [] } ], "tags": [ { "name": "Billing adjustments", "description": "Invoice adjustments (refunds) for an agreement" } ], "paths": { "/api/agreements/{agreementId}/billing-adjustments": { "get": { "tags": [ "Billing adjustments" ], "summary": "List billing adjustments for an agreement", "description": "Returns billing adjustments for the agreement, including pending and completed\nrequests.\n\nResults are not ordered. Filter client-side on `originalInvoiceId` or `status`\nif you need a subset.\n\nEach record includes `description` and, when present, `statusMessage` with\ndetails about validation failures.\n", "operationId": "listBillingAdjustments", "parameters": [ { "$ref": "#/components/parameters/agreementId" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Billing adjustments for the agreement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingAdjustmentList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/AgreementNotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "components": { "securitySchemes": { "tackleAuth": { "type": "http", "scheme": "bearer", "description": "Machine-to-machine bearer token from the Tackle client-credentials flow.\nExchange your client ID and secret at `POST /mtm/v1/authenticate` on the\nTackle platform API and send the returned token as\n`Authorization: Bearer `.\n" } }, "parameters": { "agreementId": { "name": "agreementId", "in": "path", "required": true, "description": "Agreement identifier", "schema": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z0-9_/-]+$", "example": "agmt-108thhmmjuh4xup41tmxqu23e" } }, "cursor": { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the `next` attribute of a previous response. Omit to start at\nthe first page.\n", "schema": { "type": "string" } }, "limit": { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return in one page", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } }, "schemas": { "BillingAdjustmentList": { "type": "object", "required": [ "billingAdjustments" ], "properties": { "billingAdjustments": { "type": "array", "items": { "$ref": "#/components/schemas/BillingAdjustment" } }, "next": { "$ref": "#/components/schemas/NextCursor" } } }, "NextCursor": { "type": "string", "description": "Opaque cursor for the next page. Absent on the last page — its absence, not an\nempty collection, is how you know the walk is finished.\n", "example": "eyJwayI6IlYjTVBTRUxMRVJURVNUVkVORE9SIn0=" }, "BillingAdjustmentStatus": { "type": "string", "description": "Current state of the billing adjustment.\n\n| Value | Meaning |\n|---|---|\n| `PENDING` | Accepted and processing. Usually completes within 72 hours. |\n| `COMPLETED` | Applied. A credit memo may appear as a new invoice. |\n| `VALIDATION_FAILED` | Rejected. See `statusMessage` for details. |\n", "enum": [ "PENDING", "COMPLETED", "VALIDATION_FAILED" ] }, "BillingAdjustmentReasonCode": { "type": "string", "description": "Why you are requesting the adjustment. Not interchangeable with cancellation\nreason codes.\n", "enum": [ "ALTERNATIVE_PROCUREMENT_CHANNEL", "BUYER_DISSATISFACTION", "INCORRECT_METERING", "INCORRECT_TERMS_ACCEPTED", "OTHER", "TEST_ENVIRONMENT_CHARGES", "UNINTENDED_RENEWAL" ] }, "BillingAdjustment": { "type": "object", "required": [ "id", "vendorId", "agreementId", "originalInvoiceId", "adjustmentAmount", "currencyCode", "status", "created", "lastModified" ], "properties": { "id": { "type": "string", "example": "ba-0a1b2c3d4e5f" }, "vendorId": { "type": "string", "example": "MPSELLERTESTVENDOR" }, "agreementId": { "type": "string", "example": "agmt-108thhmmjuh4xup41tmxqu23e" }, "originalInvoiceId": { "type": "string", "description": "The invoice being adjusted", "example": "inv-0a1b2c3d4e5f" }, "adjustmentAmount": { "type": "string", "description": "Unsigned refund amount as a decimal string (for example, `\"200.00\"`). The\nresource type implies a credit. Returned exactly as submitted.\n", "example": "200.00" }, "currencyCode": { "type": "string", "example": "USD" }, "status": { "$ref": "#/components/schemas/BillingAdjustmentStatus" }, "adjustmentReasonCode": { "$ref": "#/components/schemas/BillingAdjustmentReasonCode" }, "description": { "type": "string", "description": "Optional note you supplied when creating the adjustment. Omitted when empty.\n", "maxLength": 500 }, "statusMessage": { "type": "string", "description": "Details about the current status. Populated when status is\n`VALIDATION_FAILED`. Omitted when empty.\n", "example": "Refund amount $999999.00 exceeds maximum refundable amount $200.00" }, "created": { "type": "string", "format": "date-time" }, "lastModified": { "type": "string", "format": "date-time" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable explanation of the failure", "example": "Missing required parameters" } } } }, "responses": { "BadRequest": { "description": "The request is malformed or missing required parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Missing required parameters" } } } }, "Unauthorized": { "description": "The bearer token is missing, malformed, or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Unauthorized" } } } }, "Forbidden": { "description": "The token is valid but is not permitted to perform this action.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Forbidden" } } } }, "AgreementNotFound": { "description": "The parent agreement does not exist for your account. An agreement that exists\nbut has no sub-resources returns `200` with an empty collection instead.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Agreement not found" } } } }, "InternalServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Internal server error" } } } } } } } ```