Purchases

Endpoint

Individual purchase details and refund initiation.

Retrieve purchase details

GET

https://api.preo.dev

/v1/purchases/{id}

Get detailed information about a specific purchase

Retrieve purchase details › path Parameters

id

string · required

A unique value identifying this purchase.

Retrieve purchase details › Responses

200

No response body

No data returned

Create refund request for purchase

POST

https://api.preo.dev

/v1/purchases/{id}/refund

Create a new refund request for this purchase. Reason is required; scope is auto-derived from reason but can be overridden if allowed.

Create refund request for purchase › path Parameters

id

string · required

A unique value identifying this purchase.

Create refund request for purchase › Request Body

Serializer for creating refund requests via purchase context. Used with: POST /api/backoffice/purchases/{purchaseId}/refund/ The API is reason-driven: - reason is REQUIRED - scope is auto-derived from reason, but can be overridden (if allowed) - amount is auto-calculated for non-custom scopes

reason

string · enum · required

Business reason for the refund (REQUIRED)

deposit_reclaim - Deposit reclaimed
sold_out - Item sold out
event_cancelled - Event cancelled
product_defect - Product defective
duplicate_purchase - Duplicate purchase
customer_request - Customer requested
compensation - Customer compensation
overcharge - Customer overcharged
other - Other reason
rental_return - Rental returned

Enum values:

deposit_reclaim

sold_out

event_cancelled

product_defect

duplicate_purchase

customer_request

compensation

overcharge

Scope of refund (optional - auto-derived from reason, can be overridden if allowed)

purchase_price - Price only
purchase_deposit - Deposit only
purchase_full - Full purchase (incl. fees)
purchase_custom - Custom purchase amount
transaction_full - Full transaction
transaction_custom - Custom transaction amount

amount

number | null · double

Refund amount (required for CUSTOM scope, calculated automatically for others)

comment

string

Optional comment explaining the refund reason

Default:

pickup_point_id

string | null

Pickup point where refund is processed

Create refund request for purchase › Responses

id

string · readOnly · required

edition_id

string · readOnly · required

readOnly · required

amount

number · double · required

object · readOnly · required

Staff user serializer for nested representations

object · readOnly · required

Simple pickup point serializer for nested representations

created

string · date-time · readOnly · required

modified

string · date-time · readOnly · required

can_approve

string · readOnly · required

can_reject

string · readOnly · required

organization

string | null

scope

string · enum

purchase_price - Price only
purchase_deposit - Deposit only
purchase_full - Full purchase (incl. fees)
purchase_custom - Custom purchase amount
transaction_full - Full transaction
transaction_custom - Custom transaction amount

Enum values:

purchase_price

purchase_deposit

purchase_full

purchase_custom

transaction_full

transaction_custom

status

string · enum

requested - requested
ready - ready
processing - processing
awaiting_gateway - awaiting gateway
processed - processed
failed - failed
rejected - rejected
invalid - invalid

Enum values:

requested

ready

processing

awaiting_gateway

processed

failed

rejected

invalid

comment

string | null

Comment added upon custom refund

service_response

refund_date

string | null · date-time

Date when refund was successfully processed

POST/v1/purchases/{id}/refund

curl --request POST \
  --url https://api.preo.dev/v1/purchases/:id/refund \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "deposit_reclaim",
  "scope": "purchase_price",
  "amount": 0,
  "comment": "",
  "pickup_point_id": "pickup_point_id"
}
'

shell

Example Request Body

{
  "reason": "deposit_reclaim",
  "scope": "purchase_price",
  "amount": 0,
  "comment": "",
  "pickup_point_id": "pickup_point_id"
}

json

Example Responses

{
  "id": "id",
  "organization": "organization",
  "edition_id": "edition_id",
  "purchase": {
    "api_id": "api_id",
    "vendor_code": "vendor_code",
    "status": "paid",
    "product": {
      "api_id": "api_id",
      "name": "name",
      "is_draft": true,
      "images": [
        {
          "thumbnail": "https://www.example.com/path/to/resource",
          "optimized": "https://www.example.com/path/to/resource",
          "large": "https://www.example.com/path/to/resource",
          "original": "https://www.example.com/path/to/resource"
        }
      ]
    },
    "variant": "variant",
    "user": {
      "api_id": "api_id",
      "full_name": "full_name",
      "email": "test@example.com"
    },
    "metadata": {}
  },
  "transaction": {
    "id": "id",
    "type": "online",
    "status": "pending",
    "service": "service",
    "amount": 0,
    "currency": "eur",
    "service_fee": 0,
    "handling_fee": 0,
    "refunded_amount": 0,
    "available_refund_amount": 0,
    "created": "2024-08-25T15:00:00Z"
  },
  "scope": "purchase_price",
  "reason": "deposit_reclaim",
  "status": "requested",
  "amount": 0,
  "comment": "comment",
  "staff_user": {
    "id": "id",
    "email": "test@example.com",
    "full_name": "full_name",
    "first_name": "first_name",
    "last_name": "last_name",
    "phone_number": "phone_number",
    "avatar": "https://www.example.com/path/to/resource",
    "has_custom_avatar": true
  },
  "pickup_point": {
    "api_id": "api_id",
    "name": "name",
    "is_draft": true
  },
  "service_response": {},
  "refund_date": "2024-08-25T15:00:00Z",
  "created": "2024-08-25T15:00:00Z",
  "modified": "2024-08-25T15:00:00Z",
  "can_approve": "can_approve",
  "can_reject": "can_reject"
}

json

application/json

Orders User

Preo API

Purchases

Endpoint

Individual purchase details and refund initiation.

Retrieve purchase details

GET

https://api.preo.dev

/v1/purchases/{id}

Get detailed information about a specific purchase

Retrieve purchase details › path Parameters

id

string · required

A unique value identifying this purchase.

Retrieve purchase details › Responses

200

No response body

No data returned

Create refund request for purchase

POST

https://api.preo.dev

/v1/purchases/{id}/refund

Create a new refund request for this purchase. Reason is required; scope is auto-derived from reason but can be overridden if allowed.

Create refund request for purchase › path Parameters

id

string · required

A unique value identifying this purchase.

Create refund request for purchase › Request Body

reason

string · enum · required

Business reason for the refund (REQUIRED)

deposit_reclaim - Deposit reclaimed
sold_out - Item sold out
event_cancelled - Event cancelled
product_defect - Product defective
duplicate_purchase - Duplicate purchase
customer_request - Customer requested
compensation - Customer compensation
overcharge - Customer overcharged
other - Other reason
rental_return - Rental returned

Enum values:

deposit_reclaim

sold_out

event_cancelled

product_defect

duplicate_purchase

customer_request

compensation

overcharge

Scope of refund (optional - auto-derived from reason, can be overridden if allowed)

purchase_price - Price only
purchase_deposit - Deposit only
purchase_full - Full purchase (incl. fees)
purchase_custom - Custom purchase amount
transaction_full - Full transaction
transaction_custom - Custom transaction amount

amount

number | null · double

Refund amount (required for CUSTOM scope, calculated automatically for others)

comment

string

Optional comment explaining the refund reason

Default:

pickup_point_id

string | null

Pickup point where refund is processed

Create refund request for purchase › Responses

id

string · readOnly · required

edition_id

string · readOnly · required

readOnly · required

amount

number · double · required

object · readOnly · required

Staff user serializer for nested representations

object · readOnly · required

Simple pickup point serializer for nested representations

created

string · date-time · readOnly · required

modified

string · date-time · readOnly · required

can_approve

string · readOnly · required

can_reject

string · readOnly · required

organization

string | null

scope

string · enum

purchase_price - Price only
purchase_deposit - Deposit only
purchase_full - Full purchase (incl. fees)
purchase_custom - Custom purchase amount
transaction_full - Full transaction
transaction_custom - Custom transaction amount

Enum values:

purchase_price

purchase_deposit

purchase_full

purchase_custom

transaction_full

transaction_custom

status

string · enum

requested - requested
ready - ready
processing - processing
awaiting_gateway - awaiting gateway
processed - processed
failed - failed
rejected - rejected
invalid - invalid

Enum values:

requested

ready

processing

awaiting_gateway

processed

failed

rejected

invalid

comment

string | null

Comment added upon custom refund

service_response

refund_date

string | null · date-time

Date when refund was successfully processed

POST/v1/purchases/{id}/refund

curl --request POST \
  --url https://api.preo.dev/v1/purchases/:id/refund \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "deposit_reclaim",
  "scope": "purchase_price",
  "amount": 0,
  "comment": "",
  "pickup_point_id": "pickup_point_id"
}
'

shell

Example Request Body

{
  "reason": "deposit_reclaim",
  "scope": "purchase_price",
  "amount": 0,
  "comment": "",
  "pickup_point_id": "pickup_point_id"
}

json

Example Responses

{
  "id": "id",
  "organization": "organization",
  "edition_id": "edition_id",
  "purchase": {
    "api_id": "api_id",
    "vendor_code": "vendor_code",
    "status": "paid",
    "product": {
      "api_id": "api_id",
      "name": "name",
      "is_draft": true,
      "images": [
        {
          "thumbnail": "https://www.example.com/path/to/resource",
          "optimized": "https://www.example.com/path/to/resource",
          "large": "https://www.example.com/path/to/resource",
          "original": "https://www.example.com/path/to/resource"
        }
      ]
    },
    "variant": "variant",
    "user": {
      "api_id": "api_id",
      "full_name": "full_name",
      "email": "test@example.com"
    },
    "metadata": {}
  },
  "transaction": {
    "id": "id",
    "type": "online",
    "status": "pending",
    "service": "service",
    "amount": 0,
    "currency": "eur",
    "service_fee": 0,
    "handling_fee": 0,
    "refunded_amount": 0,
    "available_refund_amount": 0,
    "created": "2024-08-25T15:00:00Z"
  },
  "scope": "purchase_price",
  "reason": "deposit_reclaim",
  "status": "requested",
  "amount": 0,
  "comment": "comment",
  "staff_user": {
    "id": "id",
    "email": "test@example.com",
    "full_name": "full_name",
    "first_name": "first_name",
    "last_name": "last_name",
    "phone_number": "phone_number",
    "avatar": "https://www.example.com/path/to/resource",
    "has_custom_avatar": true
  },
  "pickup_point": {
    "api_id": "api_id",
    "name": "name",
    "is_draft": true
  },
  "service_response": {},
  "refund_date": "2024-08-25T15:00:00Z",
  "created": "2024-08-25T15:00:00Z",
  "modified": "2024-08-25T15:00:00Z",
  "can_approve": "can_approve",
  "can_reject": "can_reject"
}

json

application/json

Orders User