Server API

Server API requires a secretKey and must never be used in the browser.

Authentication

Server clients authenticate with an opaque API key (sk01_...) generated in the Console.

import { createServerClient } from '@01.software/sdk'

const serverClient = createServerClient({
  publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY!,
  secretKey: process.env.SOFTWARE_SECRET_KEY!, // sk01_... from Console
})

createServerToken, createApiKey, and parseApiKey are not part of SDK 0.9.0.

Orders API (`client.api`)

Method	Return Type	Description
`createOrder(params)`	`Promise<Order>`	Create an order
`updateOrder(params)`	`Promise<Order>`	Update order status
`getOrder(params)`	`Promise<Order>`	Get order by order number
`updateTransaction(params)`	`Promise<Transaction>`	Update transaction status
`checkout(params)`	`Promise<Order>`	Convert cart to order
`createFulfillment(params)`	`Promise<Fulfillment>`	Create shipment
`updateFulfillment(params)`	`Promise<Fulfillment>`	Update fulfillment status
`createReturn(params)`	`Promise<Return>`	Create a return request
`updateReturn(params)`	`Promise<Return>`	Update return status
`returnWithRefund(params)`	`Promise<{ return, transaction \| null }>`	Return + refund in one call
`validateDiscount(params)`	`Promise<DiscountValidation>`	Validate discount code
`calculateShipping(params)`	`Promise<ShippingCalculation>`	Calculate shipping fee

createOrder()

import { generateOrderNumber } from '@01.software/sdk'

const order = await serverClient.api.createOrder({
  orderNumber: generateOrderNumber(),
  customerSnapshot: { name: 'John Doe', email: 'customer@example.com', phone: '010-1234-5678' },
  orderProducts: [
    { product: 'product_id', variant: 'variant_id', quantity: 2, unitPrice: 10000 }
  ],
  totalAmount: 20000,
  shippingAddress: { recipientName: 'John Doe', phone: '010-1234-5678', address1: '123 Main St', postalCode: '10001' },
  paymentId: 'pay_123456', // optional for free orders
})

updateOrder()

const order = await serverClient.api.updateOrder({
  orderNumber: '260107482935',
  status: 'shipped',
})

Order status flow: pending → paid → preparing → shipped → delivered → confirmed / canceled

getOrder()

const order = await serverClient.api.getOrder({
  orderNumber: '260107482935',
})

updateTransaction()

const transaction = await serverClient.api.updateTransaction({
  paymentId: 'pay_123456',
  status: 'paid',
  paymentMethod: 'card',
  receiptUrl: 'https://receipt.example.com/123',
})

checkout()

Converts a cart to an order with payment info:

const order = await serverClient.api.checkout({
  cartId: 'cart_id',
  paymentId: 'pay_123456',
  orderNumber: generateOrderNumber(),
  customerSnapshot: {
    name: 'John Doe',
    email: 'john@example.com',
    phone: '010-1234-5678',
  },
})

createFulfillment()

Creates a shipment for an order:

const fulfillment = await serverClient.api.createFulfillment({
  orderNumber: '260107482935',
  carrier: 'cj',
  trackingNumber: '1234567890',
  items: [
    { orderItem: 'order_item_id', quantity: 2 },
  ],
})

Carrier is a free-form string (e.g. 'CJ Logistics', 'FedEx', 'UPS').

updateFulfillment()

Updates fulfillment status:

const fulfillment = await serverClient.api.updateFulfillment({
  fulfillmentId: 'fulfillment_id',
  status: 'shipped',
  carrier: 'cj',
  trackingNumber: '1234567890',
})

Fulfillment status: pending → packed → shipped → delivered / failed

createReturn()

const returnDoc = await serverClient.api.createReturn({
  orderNumber: '260107482935',
  reason: 'defective',
  reasonDetail: 'Screen cracked on arrival',
  returnProducts: [
    { orderItem: 'order_item_id', quantity: 1 },
  ],
  refundAmount: 10000,
})

Reasons: change_of_mind, defective, wrong_delivery, damaged, other

updateReturn()

const returnDoc = await serverClient.api.updateReturn({
  returnId: 'return_id',
  status: 'approved',
})

Return status: requested → processing → approved → completed (or rejected at any step)

returnWithRefund()

Combines return creation and refund transaction in one call:

const { return: returnDoc, transaction } = await serverClient.api.returnWithRefund({
  orderNumber: '260107482935',
  reason: 'defective',
  returnProducts: [
    { orderItem: 'order_item_id', quantity: 1 },
  ],
  refundAmount: 10000,
  paymentId: 'pay_123456',
  refundReceiptUrl: 'https://receipt.example.com/refund/123',
})

Cart API (`client.cart`)

Cart API is available on both ServerClient (with secretKey) and Client (with customer token).

Method	Return Type	Description
`getCart(cartId)`	`Promise<Cart>`	Get cart by ID
`addItem(params)`	`Promise<CartItem>`	Add item to cart
`updateItem(params)`	`Promise<CartItem>`	Update item quantity
`removeItem(params)`	`Promise<{ success }>`	Remove item from cart
`applyDiscount(params)`	`Promise<Cart>`	Apply discount code
`removeDiscount(params)`	`Promise<Cart>`	Remove discount code
`clearCart(params)`	`Promise<{ success }>`	Remove all items from cart

// Add item
const item = await client.cart.addItem({
  cartId: 'cart_id',
  product: 'product_id',
  variant: 'variant_id',
  option: 'option_id',
  quantity: 2,
})

// Update quantity
await client.cart.updateItem({
  cartItemId: item.id,
  quantity: 5,
})

// Remove
await client.cart.removeItem({
  cartItemId: item.id,
})

Product API (`client.product`)

Method	Return Type	Description
`stockCheck(params)`	`Promise<StockCheckResponse>`	Check stock for multiple variants

const result = await serverClient.product.stockCheck({
  items: [
    { variantId: 'variant_id_1', quantity: 2 },
    { variantId: 'variant_id_2', quantity: 1 },
  ],
})

// result.allAvailable → boolean
// result.results → [{ variantId, available, availableStock, requestedQuantity, error? }]

Utilities

generateOrderNumber()

Generates an order number in YYMMDDRRRRRR format (12 digits).

import { generateOrderNumber } from '@01.software/sdk'

const orderNumber = generateOrderNumber() // "260107482935"

formatOrderName()

import { formatOrderName } from '@01.software/sdk'

formatOrderName([{ product: { title: 'iPhone' } }])
// → "iPhone"

formatOrderName([
  { product: { title: 'iPhone' } },
  { product: { title: 'AirPods' } },
])
// → "iPhone 외 1건"

resolveRelation()

Normalizes Payload relationship fields. Handles the case where depth: 0 returns an ID and depth > 0 returns an object.

import { resolveRelation } from '@01.software/sdk'

const author = resolveRelation(post.author) // Author | null

01 Software

Server API

Server API

Authentication

Orders API (`client.api`)

createOrder()

updateOrder()

getOrder()

updateTransaction()

checkout()

createFulfillment()

updateFulfillment()

createReturn()

updateReturn()

returnWithRefund()

Cart API (`client.cart`)

Product API (`client.product`)

Utilities

generateOrderNumber()

formatOrderName()

resolveRelation()

On this page