{"openapi":"3.1.0","info":{"title":"ChyaKharcha API","version":"2026-10-06","description":"Sell physical, digital and print-on-demand products with ChyaKharcha handling payments (eSewa in Nepal, Stripe cards internationally), delivery (Pathao in Nepal, ChyaKharcha international shipping) and payouts.\n\nAuthenticate with `Authorization: Bearer <key>`. Secret keys (`ck_live_sk_…`) manage your shop and read orders; publishable keys (`ck_live_pk_…`) are safe in web pages and can only open checkouts. Test keys (`ck_test_…`) simulate checkouts without money moving. Create keys at https://www.chyakharcha.com/developer/dashboard.\n\nAll amounts are Nepali rupees (NPR). Errors look like { \"error\": { \"type\", \"message\", \"param\" } }."},"servers":[{"url":"https://www.chyakharcha.com/api/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Account"},{"name":"Products"},{"name":"Delivery"},{"name":"Checkout"},{"name":"Orders"},{"name":"Webhooks"}],"paths":{"/me":{"get":{"operationId":"getAccount","tags":["Account"],"summary":"Which shop this key acts as","description":"A good first call: confirms the key works and names the shop it will change.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"$ref":"#/components/responses/Error"}}}},"/products":{"get":{"operationId":"listProducts","tags":["Products"],"summary":"List products","description":"Without `seller` and with a secret key: every product in your own shop, including inactive ones. With `seller`: that shop's active listings. With neither: all active listings.","security":[{},{"bearerAuth":[]}],"parameters":[{"name":"seller","in":"query","schema":{"type":"string"},"description":"Shop username, e.g. smudgewears"},{"name":"type","in":"query","schema":{"type":"string","enum":["physical","digital","pod"]},"description":"Filter by kind"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Page size"},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0},"description":"Items to skip"}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"createProduct","tags":["Products"],"summary":"Create a product in your shop","description":"Secret live key. Physical products need `weight_grams` and a delivery setup in Manage Your Shop.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductCreate"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/products/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Product id"}],"get":{"operationId":"getProduct","tags":["Products"],"summary":"Get a product","security":[{},{"bearerAuth":[]}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"404":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"updateProduct","tags":["Products"],"summary":"Update a product (details, discount, stock, images, active)","description":"Only fields you send change. Listed prices are locked once a product exists (fair-pricing policy): change what buyers pay with `discount_percent`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductUpdate"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"archiveProduct","tags":["Products"],"summary":"Archive a product (sets active=false)","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/delivery/quote":{"post":{"operationId":"quoteDelivery","tags":["Delivery"],"summary":"Delivery options and fees for a physical product","security":[{},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryQuoteRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryQuote"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/checkout/sessions":{"post":{"operationId":"createCheckoutSession","tags":["Checkout"],"summary":"Open a hosted checkout for one product","description":"Send the buyer to the returned `url`. They choose options and delivery and pay with eSewa or card on chyakharcha.com, then return to `success_url?checkout_session_id=…&order_id=…`. Selling another shop's product earns you the referral share automatically.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutCreate"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSession"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/checkout/sessions/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"chk_…"}],"get":{"operationId":"getCheckoutSession","tags":["Checkout"],"summary":"Get a checkout session you opened","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSession"}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/orders":{"get":{"operationId":"listOrders","tags":["Orders"],"summary":"List paid orders","parameters":[{"name":"role","in":"query","schema":{"type":"string","enum":["seller","partner"],"default":"seller"},"description":"seller: your shop's orders; partner: orders you sold for other shops"},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","completed","cancelled"]},"description":"Fulfilment status"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Page size"},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0},"description":"Items to skip"}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Error"}}}},"/orders/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Order id"}],"get":{"operationId":"getOrder","tags":["Orders"],"summary":"Get an order","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"404":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"updateOrderStatus","tags":["Orders"],"summary":"Mark an order fulfilled or cancelled (seller)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status","note"],"properties":{"status":{"type":"string","enum":["completed","cancelled"]},"note":{"type":"string","description":"Shown to the buyer: delivery details, or the reason for cancelling."}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/webhook_endpoints":{"get":{"operationId":"listWebhookEndpoints","tags":["Webhooks"],"summary":"List webhook endpoints for this key's mode","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"createWebhookEndpoint","tags":["Webhooks"],"summary":"Register a webhook endpoint (returns its signing secret)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["order.paid","order.updated","checkout.completed","product.updated"]}},"description":{"type":"string"}}}}}},"responses":{"201":{"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"}}}},"/webhook_endpoints/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"we_…"}],"delete":{"operationId":"deleteWebhookEndpoint","tags":["Webhooks"],"summary":"Delete a webhook endpoint","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ck_live_sk_…"}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request","authentication_required","permission_denied","not_found","conflict","rate_limited","api_error"]},"message":{"type":"string"},"param":{"type":"string"}}}}}}}}},"schemas":{"Account":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":"string"},"name":{"type":"string"},"shop_url":{"type":"string"},"product_count":{"type":"integer"},"key":{"type":"object","properties":{"kind":{"type":"string"},"livemode":{"type":"boolean"}}}}},"Product":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["physical","digital"]},"print_on_demand":{"type":"boolean"},"active":{"type":"boolean"},"currency":{"const":"NPR"},"price_npr":{"type":"number","description":"Listed price"},"discount_percent":{"type":"integer"},"sale_price_npr":{"type":"number","description":"What buyers pay (before delivery)"},"sale_price_usd_approx":{"type":["number","null"]},"images":{"type":"array","items":{"type":"string"}},"weight_grams":{"type":["integer","null"]},"stock_quantity":{"type":["integer","null"],"description":"null = not tracked"},"in_stock":{"type":"boolean"},"sku":{"type":["string","null"],"description":"Only returned to the owner"},"pod_options":{"type":["object","null"]},"seller":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":"string"},"name":{"type":"string"}}},"url":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"ProductCreate":{"type":"object","required":["name","price_npr"],"properties":{"name":{"type":"string","maxLength":120,"description":"Unique within your shop"},"description":{"type":"string","maxLength":5000},"type":{"type":"string","enum":["physical","digital"],"default":"physical"},"price_npr":{"type":"number","minimum":1,"description":"Fixed after creation"},"discount_percent":{"type":"integer","minimum":0,"maximum":90},"weight_grams":{"type":"integer","minimum":1,"maximum":10000,"description":"Required for physical products"},"stock_quantity":{"type":["integer","null"],"minimum":0,"description":"Omit or null to not track stock"},"sku":{"type":"string","maxLength":64},"images":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":8,"description":"https image URLs; copied into ChyaKharcha storage"},"active":{"type":"boolean","default":true}}},"ProductUpdate":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"discount_percent":{"type":"integer","minimum":0,"maximum":90},"stock_quantity":{"type":["integer","null"],"minimum":0},"sku":{"type":"string"},"weight_grams":{"type":"integer"},"images":{"type":"array","items":{"type":"string","format":"uri"}},"active":{"type":"boolean"},"price_npr":{"type":"number","description":"Rejected for existing custom products (fair-pricing policy)"}}},"DeliveryQuoteRequest":{"type":"object","required":["product_id","destination"],"properties":{"product_id":{"type":"integer"},"quantity":{"type":"integer","default":1},"destination":{"type":"object","required":["country","city"],"properties":{"country":{"type":"string","description":"ISO-2, e.g. NP or US"},"city":{"type":"string"},"zone_id":{"type":"integer","description":"Nepal: Pathao zone id for a live courier quote"},"state":{"type":"string","description":"US state code"},"postal_code":{"type":"string"}}}}},"DeliveryQuote":{"type":"object","properties":{"currency":{"const":"NPR"},"options":{"type":"array","items":{"type":"object","properties":{"method":{"type":"string"},"label":{"type":"string"},"fee_npr":{"type":"number"},"live_quote":{"type":"boolean"}}}},"warnings":{"type":"array","items":{"type":"string"}}}},"CheckoutCreate":{"type":"object","required":["product_id","success_url"],"properties":{"product_id":{"type":"integer"},"quantity":{"type":"integer","minimum":1,"maximum":99,"default":1},"success_url":{"type":"string","format":"uri"},"cancel_url":{"type":"string","format":"uri"},"customer_email":{"type":"string","format":"email"},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Up to 20 keys; echoed in webhooks"}}},"CheckoutSession":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","description":"Send the buyer here"},"status":{"type":"string","enum":["open","completed","expired"]},"livemode":{"type":"boolean"},"product_id":{"type":"integer"},"quantity":{"type":"integer"},"amount_npr":{"type":["number","null"]},"order_id":{"type":["string","null"]},"metadata":{"type":"object"},"expires_at":{"type":"string"}}},"Order":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["physical","digital"]},"status":{"type":"string","enum":["pending","completed","cancelled"]},"payment_status":{"type":"string"},"payment_gateway":{"type":"string","enum":["esewa","stripe","khalti","manual"]},"amount_npr":{"type":"number"},"product_amount_npr":{"type":"number"},"delivery_fee_npr":{"type":"number"},"product":{"type":"object"},"seller":{"type":"object"},"customer":{"type":"object","description":"Seller only"},"delivery":{"type":["object","null"],"description":"Seller only"},"checkout_session":{"type":["object","null"]},"created_at":{"type":"string"}}}}}}