NAV

English | Polski

Wprowadzenie

Flexible Subscriptions REST API umożliwia przeglądanie, aktualizowanie i usuwanie subskrypcji za pomocą żądań w formacie JSON. Jest w pełni zintegrowane z WordPress REST API.

Aby znaleźć przewodniki użytkownika i ogólne instrukcje, odwiedź naszą Dokumentację użytkownika.

Zgodność z WooCommerce Subscriptions (WCS)

Flexible Subscriptions REST API zostało zaprojektowane tak, aby w dużej mierze było zgodne z oficjalnym WooCommerce Subscriptions (WCS) REST API. Oznacza to:

Taka zgodność pozwala łatwo migrować istniejące integracje WCS REST API albo używać istniejących bibliotek klienckich WCS REST API przy minimalnych zmianach.

Uwierzytelnianie

Aby korzystać z REST API, musisz się uwierzytelnić. Odbywa się to przy użyciu standardowych metod uwierzytelniania WooCommerce REST API.

Zapoznaj się z oficjalnym przewodnikiem WooCommerce dotyczącym generowania kluczy REST API i uwierzytelniania.

Rozszerzone WooCommerce API z danymi subskrypcji

Wtyczka Flexible Subscriptions rozszerza standardowe WooCommerce REST API o dane i funkcjonalności związane z subskrypcjami, dzięki czemu można wygodnie pracować z subskrypcjami równolegle ze standardowymi operacjami WooCommerce.

Tworzenie subskrypcji przez API zamówień

Subskrypcje nie są tworzone bezpośrednio przez żądanie POST do endpointu /subscriptions. Zamiast tego subskrypcja jest tworzona automatycznie, gdy zostanie utworzone zamówienie zawierające produkt subskrypcyjny.

Aby utworzyć subskrypcję, wyślij żądanie do standardowego endpointu WooCommerce Orders API.

POST /wp-json/wc/v3/orders

Uwzględnij produkt subskrypcyjny w line_items Twojego żądania. Po przetworzeniu zamówienia (np. po opłaceniu) powiązana subskrypcja zostanie wygenerowana.

Przykład utworzenia zamówienia, które wygeneruje subskrypcję:

{
  "payment_method": "bacs",
  "payment_method_title": "Direct Bank Transfer",
  "set_paid": true,
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "969 Market",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "line_items": [
    {
      "product_id": 123,
      "quantity": 1
    }
  ],
  "shipping_lines": [
    {
      "method_id": "flat_rate",
      "method_title": "Flat Rate",
      "total": "10.00"
    }
  ]
}

Aby dowiedzieć się więcej, zobacz sekcję Create an order w dokumentacji WooCommerce REST API.

Rozszerzona odpowiedź zamówień o subskrypcje

Podczas tworzenia zamówień przez standardowe WooCommerce Orders API, odpowiedź będzie zawierała tablicę subscriptions z identyfikatorami subskrypcji utworzonych w wyniku danego zamówienia.

Rozszerzone właściwości zamówienia

Atrybut Typ Opis
subscriptions array Tablica identyfikatorów subskrypcji utworzonych na podstawie tego zamówienia. Zawsze dołączana do odpowiedzi. tylko do odczytu

Przykładowa odpowiedź zamówienia z subskrypcjami

{
  "id": 1230,
  "status": "completed",
  "total": "35.00",
  "date_created": "2024-06-10T10:00:00",
  "subscriptions": [1234],
  "..." : "..."
}

Subskrypcje

API subskrypcji umożliwia przeglądanie, aktualizowanie i usuwanie pojedynczych subskrypcji.

Właściwości subskrypcji

Atrybut Typ Opis
id integer Unikalny identyfikator zasobu. tylko do odczytu
parent_id integer ID zamówienia początkowego użytego do utworzenia subskrypcji. tylko do odczytu
status string Status subskrypcji. Opcje: pending, active, on-hold, pending-cancel, cancelled, expired.
currency string Waluta, w której utworzono subskrypcję, w formacie ISO.
date_created date-time Data utworzenia subskrypcji w strefie czasowej witryny. tylko do odczytu
date_created_gmt date-time Data utworzenia subskrypcji w GMT. tylko do odczytu
date_modified date-time Data ostatniej modyfikacji subskrypcji w strefie czasowej witryny. tylko do odczytu
date_modified_gmt date-time Data ostatniej modyfikacji subskrypcji w GMT. tylko do odczytu
start_date_gmt date-time Data rozpoczęcia subskrypcji w GMT. Musi być w formacie YYYY-mm-dd H:i:s.
trial_end_date_gmt date-time Data zakończenia okresu próbnego subskrypcji w GMT. Musi być w formacie YYYY-mm-dd H:i:s.
next_payment_date_gmt date-time Data następnej płatności subskrypcji w GMT. Musi być w formacie YYYY-mm-dd H:i:s.
end_date_gmt date-time Data zakończenia subskrypcji w GMT. Musi być w formacie YYYY-mm-dd H:i:s.
cancelled_date_gmt date-time Data anulowania subskrypcji w GMT. tylko do odczytu
total string Łączna kwota dla każdego odnowienia. tylko do odczytu
customer_id integer ID użytkownika będącego właścicielem subskrypcji.
billing object Adres rozliczeniowy. Zobacz Order - Billing properties.
shipping object Adres wysyłki. Zobacz Order - Shipping properties.
payment_method string ID metody płatności.
payment_method_title string Nazwa metody płatności.
customer_note string Notatka pozostawiona przez klienta podczas składania zamówienia.
billing_period string Okres rozliczeniowy subskrypcji. Opcje: D (dzień), W (tydzień), M (miesiąc) oraz Y (rok).
billing_interval integer Liczba okresów rozliczeniowych pomiędzy odnowieniami subskrypcji (np. dla okresu rozliczeniowego M i interwału 2 subskrypcja odnawia się co 2 miesiące).
meta_data array Metadane. Zobacz Order - Meta data properties.
line_items array Dane pozycji zamówienia. Zobacz Order - Line items properties.
tax_lines array Dane podatków. Zobacz Order - Tax lines properties. tylko do odczytu
shipping_lines array Dane wysyłki. Zobacz Order - Shipping lines properties.
fee_lines array Dane opłat. Zobacz Order - Fee lines properties.
coupon_lines array Dane kuponów. Zobacz Order - Coupon lines properties.

Pobierz subskrypcję

To API pobiera konkretną subskrypcję na podstawie jej ID.

Żądanie HTTP

GET /wp-json/wc/v3/subscriptions/<id>

curl https://example.com/wp-json/wc/v3/subscriptions/1234 \
    -u consumer_key:consumer_secret

Przykładowa odpowiedź JSON:

{
  "id": 1234,
  "parent_id": 1230,
  "status": "active",
  "currency": "USD",
  "date_created": "2024-06-10T10:00:00",
  "date_created_gmt": "2024-06-10T14:00:00",
  "date_modified": "2024-06-10T10:05:00",
  "date_modified_gmt": "2024-06-10T14:05:00",
  "start_date_gmt": "2024-06-10T14:00:00",
  "trial_end_date_gmt": null,
  "next_payment_date_gmt": "2024-07-10T14:00:00",
  "end_date_gmt": null,
  "cancelled_date_gmt": null,
  "total": "25.00",
  "customer_id": 1,
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "969 Market",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "969 Market",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  },
  "payment_method": "stripe",
  "payment_method_title": "Credit Card (Stripe)",
  "customer_note": "",
  "billing_period": "M",
  "billing_interval": 1,
  "meta_data": [],
  "line_items": [
    {
      "id": 5,
      "name": "Monthly Coffee Box",
      "product_id": 123,
      "quantity": 1,
      "total": "25.00"
    }
  ],
  "tax_lines": [],
  "shipping_lines": [],
  "fee_lines": [],
  "coupon_lines": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v3/subscriptions/1234"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v3/subscriptions"
      }
    ],
    "customer": [
      {
        "href": "https://example.com/wp-json/wc/v3/customers/1"
      }
    ],
    "orders": [
      {
        "href": "https://example.com/wp-json/wc/v3/subscriptions/1234/orders"
      }
    ]
  }
}

Lista wszystkich subskrypcji

To API pobiera wszystkie subskrypcje, z obsługą paginacji i filtrowania.

Żądanie HTTP

GET /wp-json/wc/v3/subscriptions

curl https://example.com/wp-json/wc/v3/subscriptions?customer=1 \
    -u consumer_key:consumer_secret

Dostępne parametry

Parametr Typ Opis
context string Zakres, w którym wykonywane jest żądanie; określa pola obecne w odpowiedzi. Opcje: view i edit. Domyślnie: view.
page integer Aktualna strona kolekcji. Domyślnie: 1.
per_page integer Maksymalna liczba elementów zwracanych w zbiorze wyników. Domyślnie: 10.
search string Ogranicz wyniki do tych pasujących do ciągu znaków w adresie rozliczeniowym lub wysyłki.
after string Ogranicz odpowiedź do zasobów utworzonych po dacie zgodnej z ISO8601.
before string Ogranicz odpowiedź do zasobów utworzonych przed datą zgodną z ISO8601.
status array Ogranicz zestaw wyników do subskrypcji o określonym statusie. Opcje: any, pending, active, on-hold, pending-cancel, cancelled, expired. Domyślnie: any.
customer integer Ogranicz zestaw wyników do subskrypcji przypisanych do określonego ID klienta.
product integer Ogranicz zestaw wyników do subskrypcji zawierających określony ID produktu.
order string Kierunek sortowania rosnąco lub malejąco. Opcje: asc i desc. Domyślnie: desc.
orderby string Sortuj kolekcję według atrybutu obiektu. Opcje: date, id, include, modified. Domyślnie: date.

Aktualizuj subskrypcję

To API pozwala na wprowadzanie zmian w subskrypcji.

Żądanie HTTP

PUT /wp-json/wc/v3/subscriptions/<id>

curl -X PUT https://example.com/wp-json/wc/v3/subscriptions/1234 \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "status": "on-hold"
}'

Przykładowa odpowiedź JSON:

{
  "id": 1234,
  "status": "on-hold",
  "date_modified": "2024-06-10T11:30:00",
  "date_modified_gmt": "2024-06-10T15:30:00",
  "...": "..."
}

Usuń subskrypcję

To API pozwala usunąć subskrypcję.

Żądanie HTTP

DELETE /wp-json/wc/v3/subscriptions/<id>

curl -X DELETE https://example.com/wp-json/wc/v3/subscriptions/1234?force=true \
    -u consumer_key:consumer_secret

Dostępne parametry

Parametr Typ Opis
force boolean Czy subskrypcja ma zostać usunięta trwale. Domyślnie: false.

Zamówienia subskrypcji

API zamówień subskrypcji umożliwia przeglądanie zamówień powiązanych z konkretną subskrypcją, takich jak pierwotne zamówienie nadrzędne oraz kolejne zamówienia odnowień.

Właściwości zamówień subskrypcji

Zamówienia subskrypcji mają te same właściwości co standardowe zamówienia WooCommerce. Zapoznaj się z sekcją Order properties w głównej dokumentacji WooCommerce REST API.

Dodatkowo każde zamówienie będzie zawierało rozszerzone informacje o relacjach i odwołania do subskrypcji.

Atrybut Typ Opis
subscription_id integer ID subskrypcji, z którą powiązane jest to zamówienie. Występuje zarówno dla zamówień pierwotnych, jak i odnowień. tylko do odczytu
subscription_relationship string Typ relacji tego zamówienia do subskrypcji. Opcje: original, renewal, switch, resubscribe. tylko do odczytu
meta_data array Tablica metadanych. Będzie zawierała wpis z key = _fsb_order_type oraz value odpowiadającym typowi relacji dla zachowania zgodności wstecznej.

Lista zamówień subskrypcji

To API pobiera wszystkie zamówienia powiązane z konkretną subskrypcją.

Żądanie HTTP

GET /wp-json/wc/v3/subscriptions/<id>/orders

curl https://example.com/wp-json/wc/v3/subscriptions/1234/orders \
    -u consumer_key:consumer_secret

Przykładowa odpowiedź JSON:

[
  {
    "id": 1235,
    "parent_id": 1234,
    "status": "completed",
    "total": "25.00",
    "date_created": "2024-07-10T10:00:00",
    "subscription_id": 1234,
    "subscription_relationship": "renewal",
    "meta_data": [
      {
        "id": 987,
        "key": "_fsb_order_type",
        "value": "renewal"
      }
    ],
    "..." : "..."
  },
  {
    "id": 1230,
    "parent_id": 0,
    "status": "completed",
    "total": "35.00",
    "date_created": "2024-06-10T10:00:00",
    "subscription_id": 1234,
    "subscription_relationship": "original",
    "..." : "..."
  }
]

Notatki subskrypcji

API notatek subskrypcji umożliwia tworzenie, przeglądanie i usuwanie pojedynczych notatek subskrypcji. Notatki subskrypcji są dodawane przez administratorów oraz programowo w celu przechowywania danych o subskrypcji lub rejestrowania zdarzeń związanych z subskrypcją.

Właściwości notatek subskrypcji

Atrybut Typ Opis
id integer Unikalny identyfikator zasobu. tylko do odczytu
author string Autor notatki subskrypcji. tylko do odczytu
date_created date-time Data utworzenia notatki subskrypcji w strefie czasowej witryny. tylko do odczytu
date_created_gmt date-time Data utworzenia notatki subskrypcji w GMT. tylko do odczytu
note string Notatka subskrypcji. wymagane
customer_note boolean Jeśli true, notatka będzie widoczna dla klientów i otrzymają oni powiadomienie. Jeśli false, notatka będzie tylko informacją dla administratora. Domyślnie: false.
added_by_user boolean Jeśli true, notatka zostanie przypisana do bieżącego użytkownika. Jeśli false, notatka zostanie przypisana do systemu. Domyślnie: false.

Utwórz notatkę subskrypcji

To API pomaga utworzyć nową notatkę dla subskrypcji.

Żądanie HTTP

POST /wp-json/wc/v3/subscriptions/<id>/notes

curl -X POST https://example.com/wp-json/wc/v3/subscriptions/1275/notes \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "note": "Example subscription note."
}'

Przykładowa odpowiedź JSON:

{
    "id": 2807,
    "author": "WooCommerce",
    "date_created": "2021-04-22T13:51:07",
    "date_created_gmt": "2021-04-22T03:51:07",
    "note": "Example subscription note.",
    "customer_note": false,
    "_links": {
        "self": [
            {
                "href": "https://example.com/wp-json/wc/v3/subscriptions/1275/notes/2807"
            }
        ],
        "collection": [
            {
                "href": "https://example.com/wp-json/wc/v3/subscriptions/1275/notes"
            }
        ],
        "up": [
            {
                "href": "https://example.com/wp-json/wc/v3/subscriptions/1275"
            }
        ]
    }
}

Pobierz notatkę subskrypcji

To API umożliwia pobranie i wyświetlenie konkretnej notatki subskrypcji.

Żądanie HTTP

GET /wp-json/wc/v3/subscriptions/<id>/notes/<note_id>

curl https://example.com/wp-json/wc/v3/subscriptions/1275/notes/2807 \
    -u consumer_key:consumer_secret

Przykładowa odpowiedź JSON:

{
    "id": 2807,
    "author": "WooCommerce",
    "date_created": "2021-04-22T13:51:07",
    "date_created_gmt": "2021-04-22T03:51:07",
    "note": "Example subscription note.",
    "customer_note": false,
    "_links": {
        "self": [
            {
                "href": "https://example.com/wp-json/wc/v3/subscriptions/1275/notes/2807"
            }
        ],
        "collection": [
            {
                "href": "https://example.com/wp-json/wc/v3/subscriptions/1275/notes"
            }
        ],
        "up": [
            {
                "href": "https://example.com/wp-json/wc/v3/subscriptions/1275"
            }
        ]
    }
}

Lista wszystkich notatek subskrypcji

To API pobiera wszystkie notatki z subskrypcji.

Żądanie HTTP

GET /wp-json/wc/v3/subscriptions/<id>/notes

curl https://example.com/wp-json/wc/v3/subscriptions/1275/notes \
    -u consumer_key:consumer_secret

Przykładowa odpowiedź JSON:

[
    {
        "id": 2716,
        "author": "WooCommerce",
        "date_created": "2021-04-19T17:21:00",
        "date_created_gmt": "2021-04-19T07:21:00",
        "note": "Payment status marked complete.",
        "customer_note": false,
        "_links": {
            "self": [
                {
                    "href": "https://example.com/wp-json/wc/v3/subscriptions/1275/notes/2716"
                }
            ],
            "collection": [
                {
                    "href": "https://example.com/wp-json/wc/v3/subscriptions/1275/notes"
                }
            ],
            "up": [
                {
                    "href": "https://example.com/wp-json/wc/v3/subscriptions/1275"
                }
            ]
        }
    },
    {
        "id": 2717,
        "author": "WooCommerce",
        "date_created": "2021-04-19T17:21:00",
        "date_created_gmt": "2021-04-19T07:21:00",
        "note": "Status changed from Pending to Active.",
        "customer_note": false,
        "_links": {
            "self": [
                {
                    "href": "https://example.com/wp-json/wc/v3/subscriptions/1275/notes/2717"
                }
            ],
            "collection": [
                {
                    "href": "https://example.com/wp-json/wc/v3/subscriptions/1275/notes"
                }
            ],
            "up": [
                {
                    "href": "https://example.com/wp-json/wc/v3/subscriptions/1275"
                }
            ]
        }
    }
]

Usuń notatkę subskrypcji

To API usuwa notatkę subskrypcji.

Żądanie HTTP

DELETE /wp-json/wc/v3/subscriptions/<id>/notes/<note_id>

curl -X DELETE https://example.com/wp-json/wc/v3/subscriptions/1275/notes/2716?force=true \
    -u consumer_key:consumer_secret

Dostępne parametry

Parametr Typ Opis
force boolean Czy notatka ma zostać usunięta trwale. Domyślnie: false.

Przykładowa odpowiedź JSON:

{
    "id": 2716,
    "author": "WooCommerce",
    "date_created": "2021-04-19T17:21:00",
    "date_created_gmt": "2021-04-19T07:21:00",
    "note": "Payment status marked complete.",
    "customer_note": false,
    "_links": {
        "self": [
            {
                "href": "https://example.com/wp-json/wc/v3/subscriptions/1275/notes/2716"
            }
        ],
        "collection": [
            {
                "href": "https://example.com/wp-json/wc/v3/subscriptions/1275/notes"
            }
        ],
        "up": [
            {
                "href": "https://example.com/wp-json/wc/v3/subscriptions/1275"
            }
        ]
    }
}