# Catalog

Merchant products and cart checkout.

## List catalog products

`GET /v1/catalog/products`

### Query parameters

- `merchantId` `string`

### Responses

#### `200`: Merchant products.

Body (`application/json`):

- `id` `string` _(required)_
- `merchantId` `string` _(required)_
- `sku` `string` _(required)_
- `name` `string` _(required)_
- `description` `string | null` _(required)_
- `prices` `object[]` _(required)_
  - `amount` `string` _(required)_: Exact minor units. Calculate with this value.
  - `asset` `string` _(required)_: ISO asset code, e.g. IDR, USD, USDC.
  - `formatted` `string` _(required)_: Machine decimal; ungrouped and dot-separated.
  - `display` `string` _(required)_: Localized display text. Never parse this value.
- `active` `boolean` _(required)_
- `metadata` `object` _(required)_
- `createdAt` `string` _(required)_
- `updatedAt` `string` _(required)_
- `version` `integer` _(required)_

#### `401`: Missing or unknown API key.

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `retryable` `boolean` _(required)_
  - `details` `object`

### Example request

```bash
curl 'https://api.mayarin.xyz/v1/catalog/products?merchantId=string'
```

```ts
fetch('https://api.mayarin.xyz/v1/catalog/products?merchantId=string')
```

## Create a product

`POST /v1/catalog/products`

### Header parameters

- `Idempotency-Key` `string` _(required)_: Stable unique key for this logical write. Keep it unchanged when retrying.

### Request body (`application/json`)

- `merchantId` `string` _(required)_
- `sku` `string` _(required)_
- `name` `string` _(required)_
- `description` `string`
- `prices` `object[]` _(required)_
  - `amount` `string` _(required)_
  - `asset` `string` _(required)_
- `metadata` `object`: Your own string pairs, sent back in webhooks. At most 20 keys of up to 64 characters, values of up to 1000, and 8 KB in all.

### Responses

#### `201`: Product created.

Body (`application/json`):

- `id` `string` _(required)_
- `merchantId` `string` _(required)_
- `sku` `string` _(required)_
- `name` `string` _(required)_
- `description` `string | null` _(required)_
- `prices` `object[]` _(required)_
  - `amount` `string` _(required)_: Exact minor units. Calculate with this value.
  - `asset` `string` _(required)_: ISO asset code, e.g. IDR, USD, USDC.
  - `formatted` `string` _(required)_: Machine decimal; ungrouped and dot-separated.
  - `display` `string` _(required)_: Localized display text. Never parse this value.
- `active` `boolean` _(required)_
- `metadata` `object` _(required)_
- `createdAt` `string` _(required)_
- `updatedAt` `string` _(required)_
- `version` `integer` _(required)_

#### `400`: Validation error.

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `retryable` `boolean` _(required)_
  - `details` `object`

#### `401`: Missing or unknown API key.

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `retryable` `boolean` _(required)_
  - `details` `object`

### Example request

```bash
curl https://api.mayarin.xyz/v1/catalog/products \
  --request POST \
  --header 'Idempotency-Key: string' \
  --header 'Content-Type: application/json' \
  --data '{
  "merchantId": "string",
  "sku": "string",
  "name": "string",
  "description": "string",
  "prices": [
    {
      "amount": "string",
      "asset": "IDR"
    }
  ],
  "metadata": {}
}'
```

```ts
fetch('https://api.mayarin.xyz/v1/catalog/products', {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'string',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    merchantId: 'string',
    sku: 'string',
    name: 'string',
    description: 'string',
    prices: [
      {
        amount: 'string',
        asset: 'IDR'
      }
    ],
    metadata: {}
  })
})
```

## Get a product

`GET /v1/catalog/products/{id}`

### Path parameters

- `id` `string` _(required)_

### Responses

#### `200`: Product.

Body (`application/json`):

- `id` `string` _(required)_
- `merchantId` `string` _(required)_
- `sku` `string` _(required)_
- `name` `string` _(required)_
- `description` `string | null` _(required)_
- `prices` `object[]` _(required)_
  - `amount` `string` _(required)_: Exact minor units. Calculate with this value.
  - `asset` `string` _(required)_: ISO asset code, e.g. IDR, USD, USDC.
  - `formatted` `string` _(required)_: Machine decimal; ungrouped and dot-separated.
  - `display` `string` _(required)_: Localized display text. Never parse this value.
- `active` `boolean` _(required)_
- `metadata` `object` _(required)_
- `createdAt` `string` _(required)_
- `updatedAt` `string` _(required)_
- `version` `integer` _(required)_

#### `404`: No product with that id.

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `retryable` `boolean` _(required)_
  - `details` `object`

### Example request

```bash
curl https://api.mayarin.xyz/v1/catalog/products/string
```

```ts
fetch('https://api.mayarin.xyz/v1/catalog/products/string')
```

## Update a product

`PATCH /v1/catalog/products/{id}`

### Path parameters

- `id` `string` _(required)_

### Header parameters

- `Idempotency-Key` `string` _(required)_: Stable unique key for this logical write. Keep it unchanged when retrying.

### Request body (`application/json`)

- `name` `string`
- `description` `string | null`
- `prices` `object[]`
  - `amount` `string` _(required)_
  - `asset` `string` _(required)_
- `active` `boolean`
- `metadata` `object`: Your own string pairs, sent back in webhooks. At most 20 keys of up to 64 characters, values of up to 1000, and 8 KB in all.

### Responses

#### `200`: Updated product.

Body (`application/json`):

- `id` `string` _(required)_
- `merchantId` `string` _(required)_
- `sku` `string` _(required)_
- `name` `string` _(required)_
- `description` `string | null` _(required)_
- `prices` `object[]` _(required)_
  - `amount` `string` _(required)_: Exact minor units. Calculate with this value.
  - `asset` `string` _(required)_: ISO asset code, e.g. IDR, USD, USDC.
  - `formatted` `string` _(required)_: Machine decimal; ungrouped and dot-separated.
  - `display` `string` _(required)_: Localized display text. Never parse this value.
- `active` `boolean` _(required)_
- `metadata` `object` _(required)_
- `createdAt` `string` _(required)_
- `updatedAt` `string` _(required)_
- `version` `integer` _(required)_

#### `404`: No product with that id.

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `retryable` `boolean` _(required)_
  - `details` `object`

### Example request

```bash
curl https://api.mayarin.xyz/v1/catalog/products/string \
  --request PATCH \
  --header 'Idempotency-Key: string' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "string",
  "description": "string",
  "prices": [
    {
      "amount": "string",
      "asset": "IDR"
    }
  ],
  "active": true,
  "metadata": {}
}'
```

```ts
fetch('https://api.mayarin.xyz/v1/catalog/products/string', {
  method: 'PATCH',
  headers: {
    'Idempotency-Key': 'string',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'string',
    description: 'string',
    prices: [
      {
        amount: 'string',
        asset: 'IDR'
      }
    ],
    active: true,
    metadata: {}
  })
})
```

## Check out a cart

`POST /v1/carts/checkout`

### Header parameters

- `Idempotency-Key` `string` _(required)_: Stable unique key for this logical write. Keep it unchanged when retrying.

### Request body (`application/json`)

- `settlementAsset` `string`
- `provider` `string`
- `payment` `object`
  - `asset` `string` _(required)_
  - `chain` `string` _(required)_
  - `payerAddress` `string`
  - `returnAddress` `string`
- `executionPath` `string`
- `metadata` `object`: Your own string pairs, sent back in webhooks. At most 20 keys of up to 64 characters, values of up to 1000, and 8 KB in all.
- `merchantReference` `string`
- `ttlSeconds` `integer`
- `merchant` `object`
  - `id` `string`
  - `name` `string`
  - `city` `string`
  - `countryCode` `string`
  - `categoryCode` `string`
- `currency` `string` _(required)_
- `lines` `object[]` _(required)_

### Responses

#### `201`: Payment intent created from the cart, with the absolute hosted checkout URL.

Body (`application/json`):

- `paymentIntent` `object` _(required)_
  - `id` `string` _(required)_
  - `status` `string` _(required)_: Payment intent lifecycle state.
  - `merchant` `object` _(required)_
    - `id` `string` _(required)_
    - `name` `string` _(required)_
    - `city` `string` _(required)_
    - `countryCode` `string` _(required)_
    - `categoryCode` `string`
  - `amount` `object` _(required)_
    - `amount` `string` _(required)_: Exact minor units. Calculate with this value.
    - `asset` `string` _(required)_: ISO asset code, e.g. IDR, USD, USDC.
    - `formatted` `string` _(required)_: Machine decimal; ungrouped and dot-separated.
    - `display` `string` _(required)_: Localized display text. Never parse this value.
  - `settlementAsset` `string` _(required)_
  - `provider` `string | null` _(required)_
  - `payment` `object | null` _(required)_
    - `asset` `string` _(required)_
    - `chain` `string` _(required)_
    - `payerAddress` `string`
  - `executionPath` `string | null` _(required)_
  - `escrow` `object | null` _(required)_: Buyer-protection escrow terms; null for an ordinary payment.
    - `holdSeconds` `integer` _(required)_
    - `arbiter` `string`
  - `source` `string` _(required)_
  - `metadata` `object` _(required)_
  - `merchantReference` `string | null` _(required)_
  - `clearingTransactionId` `string | null` _(required)_
  - `failureReason` `string | null` _(required)_
  - `createdAt` `string` _(required)_
  - `updatedAt` `string` _(required)_
  - `expiresAt` `string` _(required)_
  - `confirmedAt` `string | null` _(required)_
  - `completedAt` `string | null` _(required)_
- `url` `string` _(required)_: Absolute hosted checkout URL for the buyer. Built from the API's CHECKOUT_BASE_URL, so a storefront never has to know the checkout host.

#### `400`: Validation error.

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `retryable` `boolean` _(required)_
  - `details` `object`

#### `401`: Missing or unknown API key.

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `retryable` `boolean` _(required)_
  - `details` `object`

### Example request

```bash
curl https://api.mayarin.xyz/v1/carts/checkout \
  --request POST \
  --header 'Idempotency-Key: string' \
  --header 'Content-Type: application/json' \
  --data '{
  "settlementAsset": "IDR",
  "provider": "string",
  "payment": {
    "asset": "IDR",
    "chain": "ethereum",
    "payerAddress": "string",
    "returnAddress": "string"
  },
  "executionPath": "deposit-match",
  "metadata": {},
  "merchantReference": "string",
  "ttlSeconds": 0,
  "merchant": {
    "id": "string",
    "name": "string",
    "city": "string",
    "countryCode": "string",
    "categoryCode": "string"
  },
  "currency": "IDR",
  "lines": [
    {
      "productId": "string",
      "quantity": 0
    }
  ]
}'
```

```ts
fetch('https://api.mayarin.xyz/v1/carts/checkout', {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'string',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    settlementAsset: 'IDR',
    provider: 'string',
    payment: {
      asset: 'IDR',
      chain: 'ethereum',
      payerAddress: 'string',
      returnAddress: 'string'
    },
    executionPath: 'deposit-match',
    metadata: {},
    merchantReference: 'string',
    ttlSeconds: 0,
    merchant: {
      id: 'string',
      name: 'string',
      city: 'string',
      countryCode: 'string',
      categoryCode: 'string'
    },
    currency: 'IDR',
    lines: [
      {
        productId: 'string',
        quantity: 0
      }
    ]
  })
})
```