Developer Refund API

Preview eligibility and the original refund breakdown.

Auth

Account Bearer JWT

Scope

Owned purchase and every affected product; refunds.create is required for preview and confirmation.

Request fields

• query itemIds: string

Returns

Eligible preview with snapshot, availableItems, deadline, confirmationToken, and any unavailableReason; an existing blocking operation can return eligible:false.

Side effects

Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.

Notes

Developer JWT, refunds.create permission, and scope over every affected product are required. No payment is initiated.

[
  {
    "name": "itemIds",
    "in": "query",
    "required": false,
    "schema": {
      "type": "string"
    }
  }
]

{
  "type": "object",
  "properties": {
    "eligible": {
      "type": "boolean"
    },
    "unavailableReason": {
      "type": [
        "string",
        "null"
      ]
    },
    "confirmationToken": {
      "type": "string"
    },
    "deadline": {
      "type": "string"
    },
    "snapshot": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    },
    "availableItems": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 1
          },
          "product_id": {
            "type": "integer",
            "minimum": 1
          }
        },
        "additionalProperties": true
      }
    },
    "itemSelectionUnavailableReason": {
      "type": [
        "string",
        "null"
      ]
    },
    "operation": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}

Confirm the current preview and request the refund.

Auth

Account Bearer JWT

Scope

Owned purchase and every affected product; refunds.create is required for preview and confirmation.

Request fields

• confirm: true (required)
• confirmationToken: string (required)
• reason: string (required)
• itemIds: array

Returns

202 with operation. Track its state; acceptance is not provider completion.

Side effects

Confirm the current preview and request the refund. Review the confirmation and retry requirements before repeating the request.

Notes

Do not send amount, amountCents, or items. Custom amount requests are rejected. The original capture must be eligible and the selected items must remain unrefunded.

{
  "type": "object",
  "properties": {
    "confirm": {
      "const": true
    },
    "confirmationToken": {
      "type": "string"
    },
    "reason": {
      "type": "string",
      "minLength": 3,
      "maxLength": 1000
    },
    "itemIds": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "integer",
        "minimum": 1
      }
    }
  },
  "required": [
    "confirm",
    "confirmationToken",
    "reason"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "operation": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}

curl "https://www.soundsync.dev/api/developer/purchases/123/refund?itemIds=456" \
  -H "Authorization: Bearer DEVELOPER_TOKEN"

{
  "confirm": true,
  "confirmationToken": "TOKEN_FROM_CURRENT_PREVIEW",
  "reason": "Customer requested a product refund",
  "itemIds": [456]
}