> ## Documentation Index > Fetch the complete documentation index at: https://juo.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create a schedule adjustment > Used to create a schedule adjustment. ## Examples Skip order for the third cycle with a reason. ```json theme={null} { "customerId": "cus_abc123", "matcher": { "type": "CYCLE", "input": { "cycle": 3 } }, "action": { "type": "SKIP_ORDER", "input": { "reason": "Customer on vacation" } } } ``` Reschedule order for the second cycle to a new date. ```json theme={null} { "customerId": "cus_abc123", "matcher": { "type": "CYCLE", "input": { "cycle": 2 } }, "action": { "type": "CHANGE_DATE", "input": { "newDate": "2025-02-15T00:00:00Z" } } } ``` `CHANGE_DATE` only supports the `CYCLE` matcher. The new date must be within one billing cycle of the original date and cannot be in the past. Skip all orders scheduled for a specific date. ```json theme={null} { "customerId": "cus_abc123", "matcher": { "type": "DATE", "input": { "date": "2025-01-01T00:00:00Z" } }, "action": { "type": "SKIP_ORDER", "input": { "reason": "Holiday closure" } } } ``` Update shipping address for a specific cycle. ```json theme={null} { "customerId": "cus_abc123", "matcher": { "type": "CYCLE", "input": { "cycle": 3 } }, "action": { "type": "UPDATE_SHIPPING", "input": { "address": { "firstName": "John", "lastName": "Doe", "address1": "123 Main St", "city": "New York", "countryCode": "US", "zip": "10001" } } } } ``` Address must include at least `address1` and `countryCode`. Update payment method for a specific cycle. ```json theme={null} { "customerId": "cus_abc123", "matcher": { "type": "CYCLE", "input": { "cycle": 4 } }, "action": { "type": "UPDATE_PAYMENT_METHOD", "input": { "paymentMethodId": "pm_abc123" } } } ``` Modify product lines for a specific cycle. ```json theme={null} { "customerId": "cus_abc123", "matcher": { "type": "CYCLE", "input": { "cycle": 2 } }, "action": { "type": "UPDATE_PRODUCTS", "input": { "lines": [ { "lineId": "line_abc123", "quantity": 2 }, { "lineId": "line_def456", "variantId": "variant_xyz789" }, { "lineId": "line_ghi789", "customAttributes": [ { "key": "gift_message", "value": "Happy birthday!" } ] } ] } } } ``` Each line requires `lineId`. Optional fields: `variantId` (swap variant), `quantity` (min 1), `interval` (override billing interval), `nextBillingDate`, `customAttributes` (merged onto the item by key; reserved/internal keys are rejected with a 400). Apply a Shopify discount code to a specific cycle. ```json theme={null} { "customerId": "cus_abc123", "matcher": { "type": "CYCLE", "input": { "cycle": 2 } }, "action": { "type": "APPLY_DISCOUNT", "input": { "discountSource": "code", "discountCode": "SAVE20" } } } ``` `APPLY_DISCOUNT` only supports the `CYCLE` matcher. Discount must exist in Shopify and be valid for subscriptions. Apply a manual discount to line items for a specific cycle. ```json theme={null} { "customerId": "cus_abc123", "matcher": { "type": "CYCLE", "input": { "cycle": 2 } }, "action": { "type": "APPLY_DISCOUNT", "input": { "discountSource": "manual", "discountCode": "Loyalty Reward", "discountType": "percentage", "value": 15, "targetType": "line_item", "targeting": { "type": "all" } } } } ``` Manual discounts support `targetType` of `"line_item"` or `"shipping"`, with targeting options for `"all"` or specific `"products"`. Apply a manual discount to shipping for a specific cycle. ```json theme={null} { "customerId": "cus_abc123", "matcher": { "type": "CYCLE", "input": { "cycle": 2 } }, "action": { "type": "APPLY_DISCOUNT", "input": { "discountSource": "manual", "discountCode": "Free Shipping", "discountType": "percentage", "value": 100, "targetType": "shipping", "targeting": { "type": "all" } } } } ``` Only supports free shipping discounts. For shipping discounts, `discountType` must be `"percentage"`, `value` must be `100`, `targetType` must be `"shipping"`, and `targeting` must be `{ "type": "all" }`. ## OpenAPI ````yaml openapi-admin.json POST /schedules/adjustments openapi: 3.1.0 info: title: Juo Admin API version: 1.0.0 description: >- Programmatic access to subscription management for merchants. ## Core Resources - **Subscriptions** — the central entity. Belongs to a Customer, contains Items (product variants) and Discounts. Lifecycle: `active` → `paused` or `cancelled`; `paused` → `active` or `cancelled`; `cancelled` → `active` (via reactivate). - **Items** — subscription items (product variants) (quantity, price, billing/delivery policies). - **Discounts** — applied to subscriptions by discount code or manually (percentage or fixed amount, targeting subscription items or shipping). - **Customers** — customers who own subscriptions and payment methods. - **Products / Variants** — catalog products and variants that can be assigned to subscription plans. - **Schedules** — a read-only projection of upcoming billing orders, derived from subscription state, active schedule adjustments, and triggered workflows. **Schedule adjustments never modify the subscription** — they apply changes to upcoming orders matching the specified criteria (by cycle, date, or both), which may cover one or more orders. For permanent changes (billing frequency, items, payment method, delivery address), update the subscription directly. - **Workflows** — interactive customer-facing flows (retention, dunning, onboarding). Contain Steps connected by Transitions and produce Runs on each execution. Supports A/B experiment steps. ## Authentication Every request requires: - `X-Juo-Admin-Api-Key` header — the merchant's Admin API key. - `X-Tenant-ID` header — the store identifier (myshopify domain, e.g. `my-store.myshopify.com`). servers: - url: https://api.juo.io/admin/v1 security: - AdminApiKey: [] - BearerToken: [] tags: - name: subscriptions description: >- Recurring billing agreements with customers. Manage lifecycle (pause, resume, cancel, reactivate), items, and discounts. - name: customers description: Customers who own subscriptions. Create and update customer records. - name: products description: >- Products and variants linked to subscription plans. Manage catalog and plan assignments. - name: schedules description: >- Read-only view of upcoming billing orders generated from subscription state, schedule adjustments, and workflows. Use schedule adjustments for targeted changes to upcoming orders (scoped by cycle number, date, or both) — they never alter the subscription itself. For permanent changes (billing frequency, items, payment method), update the subscription directly. - name: workflows description: >- Interactive customer-facing flows for retention, dunning, and onboarding. Define steps, publish, and track execution runs and experiments. paths: /schedules/adjustments: post: tags: - schedules summary: Create a schedule adjustment description: >- Creates a modification to upcoming orders matched by cycle number, date, or both. Adjustments can match a single order or a range of orders depending on the matcher criteria. This does NOT change the subscription — it only affects the matched upcoming order(s). Supported types: skip order, change date, update shipping address or method, change payment method, modify products (add/remove/change quantity), or apply a discount. For permanent changes, update the subscription directly. parameters: - $ref: '#/components/parameters/TenantHeader' requestBody: content: application/json: schema: type: object properties: customerId: minLength: 1 description: The customer identifier type: string matcher: anyOf: - description: Match by cycle number type: object properties: type: type: string enum: - CYCLE input: type: object properties: cycle: minimum: 0 description: Target cycle number type: integer required: - cycle required: - type - input - description: Match by date type: object properties: type: type: string enum: - DATE input: type: object properties: date: format: date-time description: Target date for the adjustment type: string required: - date required: - type - input - description: Match by both cycle and date type: object properties: type: type: string enum: - CYCLE_AND_DATE input: type: object properties: cycle: minimum: 0 description: Target cycle number type: integer date: format: date-time description: Target date for the adjustment type: string required: - cycle - date required: - type - input action: anyOf: - description: Skip an order in the schedule type: object properties: type: type: string enum: - SKIP_ORDER input: type: object properties: reason: description: Reason for skipping the order type: string required: - reason required: - type - input - description: Change the date of an order in the schedule type: object properties: type: type: string enum: - CHANGE_DATE input: type: object properties: newDate: format: date-time description: New date for the order (ISO 8601) type: string required: - newDate required: - type - input - description: >- Update the shipping address for a specific order in the schedule type: object properties: type: type: string enum: - UPDATE_SHIPPING input: type: object properties: address: type: object properties: firstName: type: - 'null' - string lastName: type: - 'null' - string address1: type: - 'null' - string address2: type: - 'null' - string zip: type: - 'null' - string city: type: - 'null' - string countryCode: type: - 'null' - string provinceCode: type: - 'null' - string phone: type: - 'null' - string company: type: - 'null' - string required: - address required: - type - input - description: >- Update the payment method for a specific order in the schedule type: object properties: type: type: string enum: - UPDATE_PAYMENT_METHOD input: type: object properties: paymentMethodId: minLength: 1 description: >- The payment method identifier to use for this order type: string required: - paymentMethodId required: - type - input - description: Update products in an order in the schedule type: object properties: type: type: string enum: - UPDATE_PRODUCTS input: type: object properties: lines: minItems: 1 type: array items: type: object properties: lineId: description: ID of the line to modify type: string variantId: description: New variant ID to swap to type: string quantity: minimum: 1 description: New quantity for the line type: integer interval: description: Override billing interval for this cycle type: object properties: intervalCount: minimum: 1 description: Number of intervals type: integer interval: description: Interval unit anyOf: - type: string enum: - DAY - type: string enum: - WEEK - type: string enum: - MONTH - type: string enum: - YEAR required: - intervalCount - interval nextBillingDate: format: date-time description: Override next billing date (ISO 8601) type: string customAttributes: description: >- Custom attributes to merge onto the order item type: array items: type: object properties: key: minLength: 1 description: Attribute key type: string value: description: Attribute value type: string required: - key - value required: - lineId required: - lines required: - type - input - description: >- Apply a discount (code or manual) to an order in the schedule type: object properties: type: type: string enum: - APPLY_DISCOUNT input: anyOf: - type: object properties: discountSource: type: string enum: - code discountCode: minLength: 1 description: The discount code to apply type: string required: - discountSource - discountCode - type: object properties: discountSource: type: string enum: - manual discountCode: minLength: 1 description: Custom discount title/name type: string discountType: anyOf: - type: string enum: - percentage - type: string enum: - fixed_amount value: minimum: 0 description: >- Discount value (percentage 0-100 or fixed amount in shop currency) type: number targetType: type: string enum: - line_item targeting: anyOf: - type: object properties: type: type: string enum: - all required: - type - type: object properties: type: type: string enum: - products productIds: type: array items: type: string variantIds: type: array items: type: string required: - type - productIds - variantIds required: - discountSource - discountCode - discountType - value - targetType - targeting - type: object properties: discountSource: type: string enum: - manual discountCode: minLength: 1 description: Custom discount title/name type: string discountType: type: string enum: - percentage value: description: >- Must be 100 — only free shipping (100% off) is supported type: number enum: - 100 targetType: type: string enum: - shipping targeting: type: object properties: type: type: string enum: - all required: - type required: - discountSource - discountCode - discountType - value - targetType - targeting required: - type - input required: - customerId - matcher - action required: true responses: '201': description: Default Response content: application/json: schema: $ref: '#/components/schemas/ScheduleAdjustment' '400': description: >- Bad request — invalid input or violated business rule (e.g., wrong subscription status for the requested operation). '401': description: Unauthorized — missing, expired, or invalid API key. '403': description: Forbidden — authenticated but not permitted to access this resource. '404': description: >- Not found — the resource does not exist or belongs to a different tenant. '422': description: >- Unprocessable entity — well-formed request that fails semantic validation. components: parameters: TenantHeader: name: X-Tenant-ID x-speakeasy-name-override: tenant x-speakeasy-globals-hidden: true in: header schema: type: string required: true description: >- Unique identifier of the tenant in the system (usually a store identifier) schemas: ScheduleAdjustment: type: object properties: id: format: uuid description: The adjustment identifier type: string resource: type: string enum: - schedule_adjustment customer: minLength: 1 description: The customer identifier type: string matcher: type: object properties: type: minLength: 1 type: string input: {} required: - type - input action: type: object properties: type: minLength: 1 type: string input: {} required: - type - input actor: type: object properties: type: type: string enum: - staff - customer - system - bulk-action - api id: description: The actor identifier, if applicable type: - 'null' - string required: - type - id createdAt: format: date-time description: Creation date of the adjustment type: string updatedAt: format: date-time description: Last update date of the adjustment type: string required: - id - resource - customer - matcher - action - actor - createdAt - updatedAt title: ScheduleAdjustment securitySchemes: AdminApiKey: type: apiKey name: X-Juo-Admin-Api-Key in: header description: >- Long-lived Admin API key issued from the Juo merchant portal. Pass as the `X-Juo-Admin-Api-Key` header. BearerToken: type: http scheme: bearer bearerFormat: JWT description: >- Short-lived JWT minted via the merchant browser-session flow. Carries the authenticated staff identity so that API calls are attributed to the specific staff user in the activity log. ````