API로 수량별 가격 업데이트/편집

공개 API로 기존 수량별 가격(Volume Pricing) 규칙을 업데이트하세요. 요청 본문 전체 참조가 포함돼 있어요.

이 문서에서는 공개 API를 사용해 기존 Volume Pricing 규칙을 업데이트하는 방법을 설명해요.

1. 엔드포인트

기존 Volume Pricing 레코드를 업데이트하려면 다음 엔드포인트를 사용하세요.

PUT https://wholesale.samita.io/api/v1/volume-pricings/{id}

{id}는 Volume Pricing 레코드의 ID예요
ID는 앱 화면에서 확인할 수 있어요(“#” 기호는 제외)
참고 예시:

예시:

PUT https://wholesale.samita.io/api/v1/volume-pricings/1

2. 요청 헤더

모든 API 요청에는 다음 필수 헤더가 포함되어야 해요.

헤더	설명	필수
`X-SAMITA-API-KEY`	Wholesale 앱에서 제공하는 API 키	예
`X-SAMITA-SHOP-URL`	xxx.myshopify.com 형식의 Shopify 스토어 도메인	예
`CONTENT-TYPE`	`application/json`이어야 해요	예

필수 헤더가 누락되면 요청이 거부돼요.

3. 요청 본문

_ Volume Pricing을 업데이트하는 데 사용하는 데이터는 JSON 형식으로 전송해야 해요. 샘플 JSON 구조는 이 문서 끝부분에 있어요.

_ 요청에는 업데이트할 필드만 포함하면 돼요. Create API 방식처럼 모든 필드를 보낼 필요는 없어요.

_ 지정하지 않은 필드는 변경되지 않아요

샘플 요청 JSON:

{
  "title": "New Volume Pricing",
  "status": true,
  "type": "quantity",
  "apply_customer": {
    "type": "all",
    "tags": []
  },
  "exclude_customer": {
    "type": "none",
    "tags": []
  },
  "apply_product": {
    "type": "all",
    "product_ids": [],
    "product_tags": [],
    "collection_ids": [],
    "apply_for_variants": false
  },
  "exclude_product": {
    "type": "none",
    "product_ids": [],
    "collection_ids": []
  },
  "discount_for_variants": [
    {
      "id": 8516448190631,
      "duplicated": false,
      "variant_pricing": true,
      "from_qty": "0",
      "from_amount": "0",
      "to_qty": "10",
      "to_amount": "0",
      "discount_groups": [
        {
          "name": "all",
          "type": "percent",
          "value": "10"
        }
      ],
      "variants": [
        {
          "id": 46747346763943,
          "duplicated": false,
          "from_qty": "0",
          "from_amount": "0",
          "to_qty": "10",
          "to_amount": "0",
          "discount_groups": [
            {
              "name": "all",
              "type": "percent",
              "value": "10"
            }
          ]
        }
      ]
    }
  ],
  "apply_market": {
    "type": "all",
    "handle": []
  },
  "discount_method": "variant",
  "discount_groups": [
    {
      "from_qty": "0",
      "from_amount": "0",
      "to_qty": "10",
      "to_amount": "0",
      "type": "percent",
      "value": "10"
    }
  ],
  "active_date": {
    "types": ["start date", "end date"],
    "start_at": "2026-01-15T10:00:00",
    "end_at": "2026-01-15T10:00:00"
  }
}

b. title

Volume Pricing 레코드를 식별하는 데 사용하는 이름
문자열이어야 해요
최대 길이: 255자

c. status

레코드의 활성 여부를 정의해요
다음 값만 허용돼요.

값	설명
`true`	가격 규칙이 활성 상태예요
`false`	가격 규칙이 비활성 상태예요

d. type

수량별 가격을 수량 기준으로 계산할지 금액 기준으로 계산할지 정의해요.

허용되는 값:

quantity
amount

e. apply_customer

이 가격 규칙을 적용할 고객을 정의해요.

구조:

"apply_customer": {
    "type": "all",
    "tags": []
}

type

허용되는 값(다음 중 하나만):

all – 모든 고객에게 적용
logged – 로그인한 고객에게만 적용
non-logged – 비회원 고객에게만 적용
customer-tags – 특정 태그가 있는 고객에게만 적용

tags

type == customer-tags일 때만 필수
쉼표로 구분된 배열이어야 해요
예시: ["wholesale","b2b"]

type이 customer-tags가 아니면 이 필드는 무시해도 돼요.

f. exclude_customer

특정 고객을 가격 규칙에서 제외하는 데 사용해요.

구조:

"exclude_customer": {
    "type": "none",
    "tags": []
}

type

기본값: none
허용되는 값:

값	설명
`none`	제외하는 고객 없음
`customer-tags`	태그로 고객 제외

tags

type == customer-tags일 때만 필수
쉼표로 구분된 배열
예시: ["vip","internal"]

g. apply_product

가격 규칙을 적용할 제품을 정의해요.

구조:

"apply_product": {
    "type": "all",
    "product_ids": [],
    "product_tags": [],
    "collection_ids": [],
    "apply_for_variants": false
 },

type

허용되는 값:

all
products
collections
product-tags

product_ids

type == products일 때만 필수
쉼표로 구분된 제품 ID 목록
Example: [1,2,3]

product_tags

type == product-tags일 때만 필수
예시: ["tag1","tag2"]

collection_ids

type == collections일 때만 필수
Example: [1,2,3]

apply_for_variants

옵션별로 할인을 구성할 수 있는지 결정해요
허용되는 값: true 또는 false
기본값: false

h. exclude_product

규칙에서 제외할 제품을 정의해요.

구조:

"exclude_product": {
    "type": "none",
    "product_ids": [],
    "collection_ids": []
 },

type

기본값: none
허용되는 값:

값	설명
`none`	제외하는 제품 없음
`products`	특정 제품 제외
`collections`	특정 컬렉션 제외

다른 필드는 선택한 type에 따라 필요한 경우에만 필수예요.

i. discount_for_variants

제품 및/또는 옵션 수준의 할인 구성을 정의해요.

apply_product.apply_for_variants == false이면 이 필드를 비워 두세요.
apply_product.apply_for_variants == true이면 이 필드는 필수예요.
구조는 제품 구성의 배열이어야 해요.

구조:

"discount_for_variants": [
    {
      "id": 8516448190631,
      "duplicated": false,
      "variant_pricing": true,
      "from_qty": "0",
      "from_amount": "0",
      "to_qty": "10",
      "to_amount": "0",
      "discount_groups": [
        {
          "name": "all",
          "type": "percent",
          "value": "10"
        }
      ],
      "variants": [
        {
          "id": 46747346763943,
          "duplicated": false,
          "from_qty": "0",
          "from_amount": "0",
          "to_qty": "10",
          "to_amount": "0",
          "discount_groups": [
            {
              "name": "all",
              "type": "percent",
              "value": "10"
            }
          ]
        }
      ]
    }
  ],

i.1. id (필수)

제품 ID.
기존 제품과 일치해야 해요.

i.2. duplicated

제품에 수량/금액 구간이 여러 개 있는지 나타내요.

허용되는 값:

true
false

규칙:

true이면 제품에 수량/금액 구간이 여러 개 있어요.
false이면 제품에 수량/금액 구간이 하나만 있어요.

i.3. from_qty / from_amount

구간의 시작 수량 또는 금액.

규칙:

첫 번째 항목은 비워 둘 수 있어요(기본값 1).
이후의 모든 항목은 필수예요.

i.4. to_qty / to_amount

구간의 끝 수량 또는 금액.

규칙:

비워 둘 수 있어요(다음 항목의 from 값에서 1을 뺀 값으로 자동 계산돼요).
값을 지정하는 경우 다음 항목의 from 값보다 작아야 해요.

예시:

항목 1: 0–10 → 항목 2: 11–20
항목 1: 0–blank → 항목 2: 10–blank
항목 1: blank–10 → 항목 2: 11–blank

i.5. discount_groups (제품 수준)

제품 수준에서 각 수량/금액 구간의 할인 구성을 정의해요.

variant_pricing == false이면 필수예요.
variant_pricing == true이면 비워 두세요.
구성된 apply_customer.type에 해당하는 할인 객체의 배열이어야 해요.

구조:

{
    "name": "all",
    "type": "percent",
    "value": "10"
}

+ name

허용되는 값:

all(apply_customer.type == all인 경우)
logged(apply_customer.type == logged인 경우)
non-logged(apply_customer.type == non-logged인 경우)

다른 값을 지정하면 고객 태그로 처리되며, apply_customer.tags에 정의된 태그 중 하나와 일치해야 해요.

+ type

할인 유형을 정의해요.

허용되는 값:

percent – 비율 할인
amount – 가격에서 차감되는 고정 금액
fixed-amount – 최종 고정 가격

+ value

숫자여야 해요
0보다 커야 해요
type == percent이면 값은 100보다 작아야 해요

i.6. variant_pricing

옵션 수준에서 할인을 적용하는지 나타내요.

허용되는 값:

true
false

i.7. variants

옵션 수준의 할인 구성을 정의해요.

variant_pricing == true이면 필수
variant_pricing == false이면 비워 두세요
옵션 구성의 배열이어야 해요

구조:

{
  "id": 46747346763943,
  "duplicated": false,
  "from_qty": "0",
  "from_amount": "0",
  "to_qty": "10",
  "to_amount": "0",
  "discount_groups": [
    {
      "name": "all",
      "type": "percent",
      "value": "10"
    }
  ]
}

+ id (필수)

옵션 ID.

+ duplicate

옵션에 수량/금액 구간이 여러 개 있는지 나타내요.

허용되는 값:

true
false

규칙:

true이면 옵션에 구간이 여러 개 있어요.
false이면 옵션에 구간이 하나만 있어요.

+ from_qty / from_amount

시작 수량 또는 금액.

규칙:

첫 번째 항목은 비워 둘 수 있어요(기본값 1).
이후의 모든 항목은 필수예요.

+ to_qty / to_amount

끝 수량 또는 금액.

규칙:

비워 둘 수 있어요(다음 항목의 from에서 1을 뺀 값으로 자동 계산돼요).
값을 지정하는 경우 다음 항목의 from 값보다 작아야 해요.

예시:

항목 1: 0–10 → 항목 2: 11–20
항목 1: 0–blank → 항목 2: 10–blank
항목 1: blank–10 → 항목 2: 11–blank

+ discount_groups (옵션 수준)

옵션 수준에서 수량/금액 구간별 할인 구성을 정의해요.

규칙:

apply_customer.type이 다음 중 하나인 경우:
- all
- logged
- non-logged
  → 배열에는 항목이 하나만 있어야 해요.
apply_customer.type == customer-tags이면
→ 배열에는 여러 항목(고객 태그당 하나)이 있어야 해요.

name

허용되는 값:

all
logged
non-logged

다른 값을 지정하면 고객 태그로 처리되며 apply_customer.tags에 정의된 태그와 일치해야 해요.

type

허용되는 값:

percent
amount
fixed-amount

value

숫자여야 해요
0보다 커야 해요
type == percent이면 값은 100보다 작아야 해요

j. apply_market

규칙을 적용할 Shopify 시장을 정의해요.

구조:

"apply_market": {
    "type": "all",
    "handle": []
}

type

허용되는 값:

all
specific-market

handle

type == specific-market일 때만 필수
쉼표로 구분된 시장 핸들 목록
예시: ["japan","us"]

k. discount_methods

허용되는 값:

variant → 같은 옵션(Same Variant)
across_group → 옵션 혼합(Mix Variants)
within_each_group → 제품 혼합(Mix Products)

이 값은 앱에서 사용할 수 있는 옵션에 해당해요.

Example:

"discount_method": "variant",

l. discount_group

수량/금액 구간과 할인 값을 정의해요.

from_qty / from_amount

to_qty / to_amount

위에서 설명한 것과 같은 유효성 검사 규칙이 적용돼요.

허용되는 “type” 값:

percent
amount
fixed-amount

value:

0보다 커야 해요
percent이면 100보다 작아야 해요

구조:

"discount_groups": [
    {
      "from_qty": "0",
      "from_amount": "0",
      "to_qty": "10",
      "to_amount": "0",
      "type": "percent",
      "value": "10"
    }
  ],

할인 유형과 값에 대한 규칙은 위에서 설명한 것과 같아요.

m. active_date

가격 규칙의 시작 및 종료 시간을 구성하는 데 사용해요.

구조:

"active_date": {
    "types": ["start_date", "end_date"],
    "start_at": "2026-01-15 10:00:00",
    "end_at": "2026-01-15 10:00:00"
}

types

선택 사항
허용되는 값: start_date, end_date
하나 또는 둘 다 포함할 수 있으며 쉼표로 구분해요
예시: ["start_date","end_date"]

start_at

types에 start_date가 포함되어 있으면 필수
형식: YYYY-MM-DD HH:MM:SS

end_at

types에 end_date가 포함되어 있으면 필수
형식: YYYY-MM-DD HH:MM:SS

4. API 응답

a. 오류 응답

401 – Unauthorized

가능한 원인:

스토어 URL 누락
API 키 누락
잘못된 스토어 URL
잘못된 API 키
API 키가 스토어와 일치하지 않음

403 – This action is unauthorized

API 키에 Update 권한이 없음
각 API 키에는 View, Create, Update, Delete 권한을 부여할 수 있어요
이 API를 사용하려면 Update 권한이 필요해요
제공한 ID가 존재하지 않을 때도 반환돼요

429 – Too Many Requests

속도 제한 초과:

최대 5분당 1회 요청
최대 하루 50회 요청

b. 성공 응답

200 – API Success

Volume Pricing 레코드가 성공적으로 업데이트되었어요
응답은 JSON 형식으로 반환돼요

샘플 응답 JSON:

{
  "id": 1,
  "title": "New Volume Pricing",
  "status": true,
  "type": "quantity",
  "apply_customer": {
    "type": "all",
    "tags": []
  },
  "exclude_customer": {
    "type": "none",
    "tags": []
  },
  "apply_product": {
    "type": "all",
    "product_ids": [],
    "product_tags": [],
    "collection_ids": [],
    "apply_for_variants": false
  },
  "exclude_product": {
    "type": "none",
    "product_ids": [],
    "collection_ids": []
  },
  "discount_for_variants": [
    {
      "id": 8516448190631,
      "duplicated": false,
      "variant_pricing": true,
      "from_qty": "0",
      "from_amount": "0",
      "to_qty": "10",
      "to_amount": "0",
      "discount_groups": [
        {
          "name": "all",
          "type": "percent",
          "value": "10"
        }
      ],
      "variants": [
        {
          "id": 46747346763943,
          "duplicated": false,
          "from_qty": "0",
          "from_amount": "0",
          "to_qty": "10",
          "to_amount": "0",
          "discount_groups": [
            {
              "name": "all",
              "type": "percent",
              "value": "10"
            }
          ]
        }
      ]
    }
  ],
  "apply_market": {
    "type": "all",
    "handle": []
  },
  "discount_method": "variant",
  "discount_groups": [
    {
      "from_qty": "0",
      "from_amount": "0",
      "to_qty": "10",
      "to_amount": "0",
      "type": "percent",
      "value": "10"
    }
  ],
  "active_date": {
    "types": [],
    "start_at": "",
    "end_at": ""
  },
  "created_at": "2026-01-15T10:00:00",
  "updated_at": "2026-01-15T10:00:00"
}

도움이 되었나요?