판매자 사은품 행사를 등록하거나 기존 사은품 행사를 수정할 때 사용하는 API입니다.
- 사은품 행사 종료일을 설정하지 않을 경우, 서비스 영역에 행사종료일은 ‘재고 소진시까지 증정’으로 표시됩니다.
- 사은품 행사 시작일은 초 단위를 00초, 종료일은 59초로 설정해주세요.
- 사은품 행사 배너 이미지 URL은 이미지 업로드 API를 통해 BANNER 타입으로 등록한 이미지를 사용해야 합니다.
- 사은품 행사 배너 이미지 권장 사이즈는 696 × 300px 이상입니다.
- 사은품 행사 배너 이미지 파일 용량은 10MB 이하만 가능합니다.
1. 판매자 사은품 등록
요청
POST /v1/gift/special-gifts<요청 바디 필드 설명>
| 필드명 | 타입 | 필수여부 | 설명 |
|---|---|---|---|
| title | String | 필수 | 사은품 행사명 |
| period | TimePeriod | 필수 |
사은품 행사 기간 * 행사 시작일 (period.from) : 필수 * 행사 종료일 (period.to) : 선택 |
imageUrl |
String | 선택 | 사은품 행사 배너 이미지 URL |
condition |
String | 선택 | 사은품 행사 조건 (16자 이내) |
description |
String | 선택 | 사은품 행사 내용 (60자 이내) |
응답
<응답 바디>
| 필드명 | 타입 | 필수여부 | 설명 |
|---|---|---|---|
| specialGiftResponse | SpecialGiftResponse | 필수 | 사은품 행사 정보 |
2. 판매자 사은품 수정요청
PUT /v1/gift/special-gifts?id={id}<요청 파라미터 설명>
| 필드명 | 타입 | 필수여부 | 설명 |
|---|---|---|---|
| id | Long | 필수 | 사은품 행사 아이디 |
<요청 바디 필드 설명>
| 필드명 | 타입 | 필수여부 | 설명 |
|---|---|---|---|
| title | String | 필수 | 사은품 행사명 |
| period | TimePeriod | 필수 |
사은품 행사 기간 * 행사 시작일 (period.from) : 필수 * 행사 종료일 (period.to) : 선택 |
imageUrl |
String | 선택 | 사은품 행사 배너 이미지 URL |
condition |
String | 선택 | 사은품 행사 조건 (16자 이내) |
description |
String | 선택 | 사은품 행사 내용 (60자 이내) |
응답
<응답 바디>
| 필드명 | 타입 | 필수여부 | 설명 |
|---|---|---|---|
| specialGiftResponse | SpecialGiftResponse | 필수 | 사은품 행사 정보 |
3. 판매자 사은품 행사 등록/수정 요청 시, 응답 바디 샘플
<응답 바디 샘플>
{
"specialGiftId": 12345,
"title": "사은품 행사 테스트",
"timePeriod": {
"from": "20260102120000",
"to": "20260110235959"
},
"imageUrl": "https://...",
"condition": "3만원 이상 구매 시",
"description": "사은품 행사 테스트입니다.",
"displayStatus": "OPEN",
"lastModifiedAt": "20260102100000",
"lastModifiedBy": "오픈API/테스트셀러(143421)",
"createdAt": "20260102100000",
"createdBy": "오픈API/테스트셀러(143421)"
}